> ## 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.

# Sandbox configuration

> Configure branch sandbox deploy targets with .arga/sandbox.yml

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](#docker-compose-support).

## Single-app repo

For a repository with one deployable app:

```yaml theme={null}
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:

```yaml theme={null}
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

| Field             | Required | Description                                                                                    |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `context_dir`     | No       | Repository-relative Docker build context. Defaults to `.`.                                     |
| `dockerfile_path` | No       | Repository-relative Dockerfile path. Defaults to `Dockerfile`.                                 |
| `app_port`        | No       | Port exposed by the app container. Defaults to the sandbox app port.                           |
| `app_command`     | No       | Command override for the app container. Use this when the image default command is not enough. |
| `env`             | No       | Runtime environment variables added to the deployed app. Values are scoped to the sandbox run. |
| `twins`           | No       | API twins to provision with the sandbox, such as `stripe`, `slack`, or `github`.               |
| `infra`           | No       | Infrastructure services to boot with the sandbox, such as `postgres`.                          |

<Tip>
  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`.
</Tip>

## 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](/features/pr-validation#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.