> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox mode

> Run agents inside Archal's controlled Docker sandbox so service traffic reaches clones instead of production while tools, domains, and workspaces stay normal.

Sandbox mode runs your agent inside a controlled Docker container. Your agent
keeps using normal tools and service domains; supported service traffic reaches
clones instead of production.

Use normal `archal run --docker` first. Use sandbox mode when your agent must
run inside a controlled container because it expects real service domains,
installed tools, or a full workspace.

## Requirements

| Mode                        | Requires                                         |
| --------------------------- | ------------------------------------------------ |
| Docker (default)            | Docker Engine running locally                    |
| Local debug (`--no-docker`) | OpenClaw CLI installed and in `PATH`; debug-only |

Both modes require Node.js 22+ and an Archal auth token (`ARCHAL_TOKEN` or `~/.archal/credentials.json`).

## Quick start

```bash theme={null}
archal run scenarios/security-suite/exec-impersonation.md --sandbox
```

With a custom OpenClaw home directory:

```bash theme={null}
archal run scenarios/github/close-stale-issues.md \
  --sandbox \
  --openclaw-home ~/.openclaw
```

Use `--no-docker` only for local debugging. It does not provide high-fidelity
service simulation because Archal cannot control DNS and TLS trust outside the
container.

```bash theme={null}
archal run scenarios/github/close-stale-issues.md \
  --sandbox \
  --no-docker \
  --allow-low-fidelity-networking
```

## How it works

### Docker mode (default)

1. Archal provisions cloud clone sessions and gets URLs (e.g. `https://sess.clones.archal.ai/github/api`)
2. A **sidecar** container (`archal/sandbox-proxy`) starts alongside the packaged OpenClaw agent image
3. The sidecar:
   * Generates a short-lived CA certificate and writes it to `/agent-output/ca.crt`
   * Rewrites DNS for service domains to the intercept listener
   * Performs TLS interception with per-domain certificates
   * Injects fake service credentials into forwarded requests (`STRIPE_API_KEY`, `SLACK_TOKEN`, etc.)
4. The packaged OpenClaw agent container runs `drive.mjs`, which starts the local gateway and sends the scenario task to the agent
5. The harness sets `NODE_EXTRA_CA_CERTS` to the sidecar CA so the agent trusts intercepted TLS

When the agent calls `api.github.com`, traffic routes through the sidecar proxy,
swaps in the run credential, and forwards to the clone. Model-provider domains
(`api.openai.com`, `api.anthropic.com`, …) pass through to the real provider with
your host key injected by the sidecar.

### Local debug mode

Uncontainerized local execution is debug only. It is not used for scored
service simulation because Archal cannot control DNS and TLS trust there.

<Note>
  Use Docker or sandbox mode for high-fidelity runs.
</Note>

## Go deeper

* [Run with an agent](/guides/run-with-agent) covers the normal Docker path.
* [Route-mode safety](/guides/route-mode-safety) covers traffic routing and limits.
* [Docker harness contract](/guides/docker-harness-contract) covers container expectations.

## Remote OpenClaw gateway

Use this when your agent is already exposed as an OpenClaw-compatible
`/v1/responses` endpoint instead of running locally inside the sandbox.

```bash theme={null}
archal run scenario.md \
  --engine-endpoint https://agent.example.com/v1/responses \
  --engine-token "$ARCHAL_ENGINE_TOKEN" \
  --agent-model openclaw:main
```

API-mode runs require engine auth. Set `ARCHAL_ENGINE_TOKEN` or pass
`--engine-token`; otherwise the run fails before execution.

Only override clone URLs when your gateway cannot reach the hosted URLs Archal
passes by default:

* `--engine-clone-urls` for MCP clone URLs
* `--api-base-urls` for service-native REST/API base URLs

Archal stays responsible for hosted clones and evaluation. Your gateway stays
responsible for agent execution.

## Supported services

The proxy intercepts routed domains from the clone launch manifest and routes
them to clone endpoints. Use `archal clone --json` for the current hosted clone
catalog; this table is a summary, not a hand-maintained allowlist.

| Clone            | Intercepted domains                                                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Apify            | `api.apify.com`                                                                                                                                      |
| Discord          | `discord.com`, `discordapp.com`                                                                                                                      |
| GitHub           | `api.github.com`, `uploads.github.com`                                                                                                               |
| Google Workspace | `gmail.googleapis.com`, `drive.googleapis.com`, `calendar.googleapis.com`, `oauth2.googleapis.com`, `people.googleapis.com`, `sheets.googleapis.com` |
| Jira             | `atlassian.net`, `*.atlassian.net`, `api.atlassian.com`                                                                                              |
| Linear           | `api.linear.app`                                                                                                                                     |
| Ramp             | `api.ramp.com`                                                                                                                                       |
| Slack            | `slack.com`                                                                                                                                          |
| Stripe           | `api.stripe.com`                                                                                                                                     |
| Supabase         | `supabase.co`, `*.supabase.co`                                                                                                                       |
| Tavily           | `api.tavily.com`                                                                                                                                     |

Tenant-specific subdomains (e.g. `acme.atlassian.net`) are discovered from the mounted OpenClaw home and added to DNS rewrites automatically.

## What gets mounted

When you pass `--openclaw-home` (or let it default to `~/.openclaw`), the entire
OpenClaw home is mounted into the agent container read-only at `/openclaw-home`.
`drive.mjs` copies it into a writable `~/.openclaw` inside the container, preserving
the agent's personality, memory, skills, plugins, and auth profiles.

```bash theme={null}
archal run scenario.md --sandbox --openclaw-home ~/.openclaw
```

If no home is mounted, the bundled demo persona under `workspace/` is used.

If no LLM auth exists in the mounted files, set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY` as environment variables.

## GraphQL bridge

The `gh` CLI uses GraphQL for many commands (`gh issue list`, `gh repo view`, etc.). Since cloud clones expose REST endpoints, the proxy includes a GraphQL-to-REST bridge that translates common GraphQL queries into REST calls against the GitHub clone. This means `gh` commands work inside the sandbox without modification.

## Flags reference

| Flag                              | Description                                              | Default                  |
| --------------------------------- | -------------------------------------------------------- | ------------------------ |
| `--sandbox`                       | Enable sandbox mode                                      | off                      |
| `--no-docker`                     | Skip Docker for low-fidelity local debugging             | Docker mode              |
| `--allow-low-fidelity-networking` | Required opt-in for `--no-docker` local debug networking | off                      |
| `--openclaw-home <dir>`           | Full OpenClaw home directory to mount                    | `~/.openclaw`            |
| `--openclaw-version <version>`    | OpenClaw version to install in the sandbox image         | pinned in `package.json` |
| `--openclaw-eval-mode <mode>`     | Eval mode: `isolated` or `stateful`                      | -                        |

## Container resources

The sandbox agent and sidecar containers run with resource limits appropriate for agent workloads. The sidecar binds the intercept listener inside the sidecar network namespace.

## Troubleshooting

### `Docker is not available`

Install Docker. High-fidelity service simulation requires a controlled runtime.

### `OpenClaw CLI was not found in PATH`

For low-fidelity local debugging with `--no-docker`, install OpenClaw globally:

```bash theme={null}
npm install -g openclaw
```

### `Sandbox proxy does not support domain interception for: <clone>`

The requested clone does not have route-mode domain mappings in this build. Use
direct clone URLs from `archal clone start <clone>`, or choose a clone listed by
`archal clone --json` with route-mode support.

### Agent fails with TLS errors

The CA cert may not be trusted. In Docker mode this is automatic for the
sandbox image and CA trust env vars are provided for runtimes that need them.

### `gh auth status` fails

The proxy intercepts `GET /` on `api.github.com` and returns a synthetic API root response. If `gh` still fails, ensure `GH_TOKEN` is **not** set as an environment variable - it bypasses the proxy's auth header injection.