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 |
ARCHAL_TOKEN or ~/.archal/credentials.json).
Quick start
archal run scenarios/security-suite/exec-impersonation.md --sandbox
archal run scenarios/github/close-stale-issues.md \
--sandbox \
--openclaw-home ~/.openclaw
--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.
archal run scenarios/github/close-stale-issues.md \
--sandbox \
--no-docker \
--allow-low-fidelity-networking
How it works
Docker mode (default)
- Archal provisions cloud clone sessions and gets URLs (e.g.
https://sess.clones.archal.ai/github/api)
- A Docker container starts with the
archal/sandbox image
- Inside the container, the entrypoint:
- Generates a short-lived CA certificate and installs it in the container trust store
- Writes
/etc/hosts entries mapping service domains to 127.0.0.1 (e.g. 127.0.0.1 api.github.com)
- Starts TLS interception on
:443 that uses SNI to present valid per-domain certs
- Injects fake service credentials into the environment (
STRIPE_API_KEY, SLACK_TOKEN, etc.)
- Configures the
gh CLI with a dummy OAuth token
- Starts the OpenClaw gateway and sends the scenario task to the agent
When the agent calls api.github.com, the container routes that request through
the proxy, swaps in the run credential, and forwards it to the clone.
Non-cloned traffic, such as LLM API calls, passes through.
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.
Use Docker or sandbox mode for high-fidelity runs.
Go deeper
Supported services
The proxy intercepts the routed API domains declared by the clone launch manifest and routes them to clone endpoints:
| 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 |
acme.atlassian.net) are discovered from the mounted OpenClaw config and added to /etc/hosts automatically.
What gets mounted
Full home mount (default)
When you pass --openclaw-home (or let it default to ~/.openclaw), the entire OpenClaw home is copied into the container read-only. This preserves the agent’s personality, memory, skills, plugins, and auth profiles.
archal run scenario.md --sandbox --openclaw-home ~/.openclaw
Workspace-only mount
When you pass --openclaw-workspace instead, only the workspace directory is mounted. A minimal OpenClaw config is generated inside the container.
archal run scenario.md --sandbox --openclaw-workspace ./my-project
archal run scenario.md --sandbox \
--openclaw-workspace ./my-project \
--openclaw-config ./openclaw.json
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-workspace <dir> | OpenClaw workspace directory (workspace-only mode) | - |
--openclaw-config <path> | Path to openclaw.json (workspace-only mode) | - |
--openclaw-version <version> | OpenClaw version to install in the sandbox image | latest |
--openclaw-eval-mode <mode> | Eval mode: isolated or stateful | - |
Container resources
The sandbox container runs with --memory=2g --cpus=2 limits. The proxy binds :443 on 127.0.0.1 inside the container (runs as root, no special capabilities needed).
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:
Sandbox proxy does not support domain interception for: <clone>
The requested clone does not have proxy domain mappings yet. Add route-proxy domains to the clone launch manifest, then regenerate the sandbox route-domain artifact before using transparent interception for that clone.
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. 