Skip to main content
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

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

​
Quick start

With a custom OpenClaw home directory:
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.

​
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.
Use Docker or sandbox mode for high-fidelity runs.

​
Go deeper

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

​
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:

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