Skip to Content
Deploy & ConfigureSandboxCloud Run Sandboxes

Cloud Run Sandboxes

Instead of self-hosting OpenSandbox, you can run agent code on Google Cloud Run sandboxes  (public preview). In auxilia this is the Cloud Run sandbox provider, registered like any other under Settings → Sandboxes.

The backend never talks to Cloud Run directly. All sandbox traffic goes through a small dedicated Cloud Run service — the sandbox gateway — which is the only deployment that runs Google’s sandbox CLI. Your backend and worker can run anywhere (another cloud, a VM, even a laptop) and need no special launcher.

┌──────────────────┐   HTTPS + bearer secret   ┌────────────────────────┐
│ auxilia backend  │ ────────────────────────▶ │  sandbox-gateway       │
│ (anywhere)       │                           │  (Cloud Run,           │
└────────┬─────────┘                           │   --sandbox-launcher)  │
         │                                     └───────────┬────────────┘
         │  snapshot tar at end of turn                    │ sandbox CLI
         ▼                                                 ▼
┌──────────────────┐                           ┌────────────────────────┐
│  GCS bucket      │                           │  Sandbox               │
│  (optional)      │                           │  (gateway image, ro)   │
└──────────────────┘                           └────────────────────────┘

1. Deploy the gateway

From the gateway service’s directory (a FastAPI app exposing the sandbox CLI over HTTP, plus the Dockerfile that defines the sandbox runtime):

gcloud beta run deploy sandbox-gateway \
  --source . \
  --region <region> \
  --sandbox-launcher \
  --timeout=3600 \
  --allow-unauthenticated \
  --set-env-vars CLOUD_RUN_SANDBOX_GATEWAY_SECRET=$(openssl rand -hex 32)

Notes:

  • --sandbox-launcher (gen2) is required — it mounts the sandbox CLI into the service. Verify with GET /health → {"cli_mounted": true} after deploying.
  • --timeout=3600 raises Cloud Run’s request deadline (default 300 seconds) above the sandbox’s per-command Timeout (default 1800 seconds). Without it, any command running longer than 5 minutes is cut off by the platform instead of being reported as timed out.
  • --allow-unauthenticated disables Cloud Run IAM on the service. This is deliberate: the backend authenticates with the shared bearer secret only (it does not mint Google ID tokens), so IAM must be open for it to connect — every endpoint except /health rejects requests without the secret, and the gateway fails closed (503) if the secret is unset. Treat the secret like a credential: generate it with high entropy (as above), store it in a secret manager, and rotate it if leaked. If your backend runs inside the same Google Cloud project, you can additionally restrict exposure with --ingress internal plus a VPC connector instead of leaving the URL publicly reachable.
  • Set ALLOW_EGRESS=true on the gateway service if sandboxes should get outbound network access (needed for in-sandbox pip install and for Default packages). Off by default.

The gateway image is the sandbox environment

Sandboxed code sees the gateway container’s filesystem read-only, with a private writable overlay on top. Whatever is installed in the gateway’s Dockerfile is what agent code can import — edit its second pip install block (ships with numpy, pandas, matplotlib, openpyxl, requests) to change the runtime, then redeploy.

2. Register it in auxilia

In Settings → Sandboxes, click Add sandbox and pick Cloud Run:

FieldNotes
Gateway URLThe deployed service URL, https://sandbox-gateway-….run.app
Gateway secretRequired — the same value as CLOUD_RUN_SANDBOX_GATEWAY_SECRET on the gateway. Stored encrypted; a Cloud Run sandbox cannot be saved without it, because the gateway would refuse every call
GCS bucketOptional but recommended in production: where turn-end snapshots go
Snapshot prefixObject prefix inside the bucket. Default sandbox-snapshots/
Allow network egressRequest egress for each sandbox — only honored if the gateway itself runs with ALLOW_EGRESS=true
Default packages / Timeout (seconds)Extra pip packages installed into each fresh sandbox (needs egress); per-command limit, default 1800

Then bind the sandbox to an agent from the agent editor’s Add tool dialog.

3. Persistence and snapshots

A Cloud Run sandbox lives inside one gateway instance, so continuity across instances (and across gateway restarts) is handled with snapshots:

  • At the end of each agent turn, the sandbox’s writable overlay is exported as a tar and stored in the configured GCS bucket
  • At the start of the next run, the backend probes the live sandbox first; if it’s gone, it relaunches the sandbox from the last snapshot (pip installs made by the agent travel inside the snapshot)
  • Snapshots are best-effort: without a bucket (e.g. local dev against the gateway), a lost instance means a lost sandbox — the run then gets a fresh, empty one and the model is told

Alternatively, run the gateway with --max-instances 1 and session affinity to keep sandboxes on a single instance without a bucket.

Unlike OpenSandbox, Cloud Run sandboxes have no TTL — their lifetime is bounded by the host instance plus snapshot restores.

The backend also needs GCS write access to the snapshot bucket (Application Default Credentials, e.g. the service account it runs as).

Known limitations

  • Subagent sandboxes don’t get the turn-end snapshot hook yet — files written by a subagent’s sandbox may not survive a gateway instance recycle
  • Snapshot restores are capped by Cloud Run’s 32 MiB request limit — sandboxes with a very large writable overlay can’t be restored across instances
SetupSecurity