Skip to Content
Deploy & ConfigureSandboxSecurity

Sandbox Security

The sandbox lets an LLM run arbitrary shell commands against a filesystem. That is a powerful capability and worth thinking about carefully.

Isolation model

Every sandbox is an isolated container, per-conversation — the sandbox tied to thread A cannot be reached from thread B — and created on demand when the LLM calls create_sandbox; no idle containers sit around.

The auxilia backend never executes commands itself — it always delegates to the sandbox runtime. So the blast radius of a malicious prompt is whatever your sandbox deployment allows the container to do.

With OpenSandbox (SANDBOX_PROVIDER=opensandbox, the default), containers are managed by OpenSandbox  and have a TTL (default 30 minutes); after expiry they are destroyed and any state inside is lost.

With Cloud Run sandboxes (SANDBOX_PROVIDER=cloudrun):

  • Sandboxed code sees the gateway image’s filesystem read-only, with a private writable overlay per sandbox
  • Sandboxes have no outbound network access unless the gateway is deployed with ALLOW_EGRESS=true and the backend sets CLOUD_RUN_SANDBOX_ALLOW_EGRESS=true
  • The gateway requires a shared bearer secret on every request and fails closed if the secret is unset
  • If CLOUD_RUN_SANDBOX_GCS_BUCKET is set, the writable overlay is snapshotted to GCS at the end of each turn — treat that bucket as containing whatever agents write

Volume mounts (OpenSandbox only)

You can mount host paths into every sandbox via OPEN_SANDBOX_VOLUME_MOUNTS:

OPEN_SANDBOX_VOLUME_MOUNTS=/srv/shared:/workspace:ro,/tmp/auxilia:/mnt/scratch

Format: host_path:sandbox_path[:ro], comma-separated.

  • Each entry becomes a volume on every sandbox spun up by this backend
  • The :ro suffix mounts read-only
  • Host paths that don’t exist are skipped with a warning at startup
  • Host paths with ~ are expanded to the backend’s home directory

Treat the host paths you mount as public to any agent with the sandbox enabled. If you mount /srv/data read-only, every sandboxed agent can read it. If you mount /tmp/auxilia read-write, every sandbox can write to it — it is a shared scratch space.

Timeouts

Two timeouts apply:

  • Per-command timeout — OPEN_SANDBOX_TIMEOUT (or CLOUD_RUN_SANDBOX_TIMEOUT), default 1800s. If a single execute call doesn’t finish in this window, auxilia cancels it and returns exit_code=124.
  • Container TTL (OpenSandbox only) — default 30 minutes; renewed each time connect_sandbox is called. Cloud Run sandboxes have no TTL; their lifetime is bounded by the gateway instance, with GCS snapshots covering continuity.

Keep the per-command timeout tight. Long-running commands are rare in practice and chew up OpenSandbox capacity.

Authentication

The OpenSandbox controller authenticates requests with the OPEN_SANDBOX_API_KEY. Put the controller on a private network (VPC, internal DNS) and only let the auxilia backend reach it.

Setting OPEN_SANDBOX_USE_SERVER_PROXY=true routes the agent’s file reads/writes through the OpenSandbox server rather than direct container ports, which is simpler in firewalled environments.

A safe default for most teams:

  • Run OpenSandbox on an internal-only host or VPC
  • Never mount sensitive host paths — let the sandbox stay ephemeral
  • Keep the per-command timeout at 30 min or less
  • Turn Code execution on only for agents whose owners trust the LLM to run code against the configured image
  • Use tool approvals on non-sandbox write tools (HubSpot writes, GitHub PRs) to keep a human in the loop even when the agent is autonomous inside the sandbox

If you need stronger guarantees, gate the sandbox toggle behind a workspace-admin-only agent, and use the permissions model to restrict who can chat with it.

Cloud Run SandboxesObservability (Langfuse)