Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt

Use this file to discover all available pages before exploring further.

Use .arga/sandbox.yml or .arga/sandbox.yaml to tell Arga how to deploy a repository branch into a sandbox. This is especially useful for monorepos where the app Dockerfile is not at the repository root. Arga reads the file during sandbox and PR-run planning. The selected target controls the Docker build context, Dockerfile path, app port, optional start command, runtime environment variables, and extra twins to provision.

​
Single-app repo

For a repository with one deployable app: 
app:
  context_dir: .
  dockerfile_path: Dockerfile
  app_port: 8000
  app_command: uvicorn app.main:app --host 0.0.0.0 --port 8000
  env:
    FEATURE_FLAG: "true"
  twins:
    - postgres
    - stripe

​
Monorepo

For a monorepo, define named targets and choose the default target: 
default_target: web

targets:
  web:
    context_dir: apps/web
    dockerfile_path: apps/web/Dockerfile
    app_port: 3000
    app_command: npm run start -- --port 3000
    env:
      NEXT_PUBLIC_API_URL: http://app:3000
    twins:
      - stripe

  api:
    context_dir: services/api
    dockerfile_path: services/api/Dockerfile
    app_port: 8000
    twins:
      - postgres
If default_target is omitted, Arga uses the first target in the file.

​
Fields

FieldRequiredDescription
context_dirNoRepository-relative Docker build context. Defaults to ..
dockerfile_pathNoRepository-relative Dockerfile path. Defaults to Dockerfile.
app_portNoPort exposed by the app container. Defaults to the sandbox app port.
app_commandNoCommand override for the app container. Use this when the image default command is not enough.
envNoRuntime environment variables added to the deployed app. Values are scoped to the sandbox run.
twinsNoAdditional twins to provision with the sandbox, such as postgres, stripe, or slack.
If your app uses Postgres, include postgres in twins or let Arga detect common Postgres signals such as alembic.ini. When no workspace database mirror is configured, Arga boots an empty sandbox Postgres and injects DATABASE_URL.

​
How Arga applies it

  1. Arga fetches .arga/sandbox.yml or .arga/sandbox.yaml from the branch being deployed.
  2. It selects default_target, or the first target if no default is set.
  3. It stores the selected target on the run runtime profile.
  4. The deploy builder uses the target’s context_dir and dockerfile_path.
  5. The sandbox runtime applies the target’s app_port, app_command, env, and twins.
Manual values entered in the sandbox UI can still override run-specific environment variables and command settings.