Skip to main content
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, API twins to provision, and infrastructure services to boot alongside the app. Arga also supports repositories that ship a docker-compose.yml at the repo root. When a compose file is detected, Arga builds each compose service as part of the sandbox and merges them with the requested twins and gateway. See Docker Compose support.

​
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:
    - stripe
  infra:
    - postgres

​
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
    infra:
      - 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.
twinsNoAPI twins to provision with the sandbox, such as stripe, slack, or github.
infraNoInfrastructure services to boot with the sandbox, such as postgres.
If your app uses Postgres, include postgres in infra or let Arga detect common Postgres signals such as alembic.ini. Postgres is an infrastructure service, not an API twin. 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, twins, and infra.
Manual values entered in the sandbox UI can still override run-specific environment variables and command settings.

​
Docker Compose support

If your repository contains a docker-compose.yml (or docker-compose.yaml) at the root, Arga can deploy the full multi-service compose application as a sandbox alongside your selected API twins. When compose mode is active:
  • Each service in the compose file is built into a per-service image tagged for the sandbox preview, and the rendered runtime compose references those images instead of local build: entries.
  • The compose services are merged onto the same Docker network as the twin gateway and selected twins, so traffic to external APIs is intercepted by twins automatically.
  • A shared ./env/runtime.env file is injected into every compose service so that runtime environment variables (including resolved ARGA_PREVIEW_* tokens) are available alongside any env_file your compose definition already declares.
  • Repo-relative bind mounts in the compose file are dropped from the rendered sandbox compose, since the sandbox runs from built images rather than the local repo checkout.
  • Public service ports declared by the compose file are exposed through the sandbox preview URL. The first public service is also reachable via ARGA_PREVIEW_URL_APP, and each service that publishes ports gets a per-service URL such as ARGA_PREVIEW_URL_BACKEND. See Preview environment variables for the full list.
Compose-backed sandboxes use the same twin selection and routing modes as Dockerfile-backed sandboxes — selecting twins for the run still wires the twin gateway in front of your compose services so outbound calls to integrated services are intercepted.