Skip to main content
Anything on the platform that runs code — the agent Sandbox and Code Execution tools, code-execution flow nodes, plugin nodes, and the /v1/sandboxes API — executes inside an isolated sandbox. As an operator you choose which sandbox backend runs that code, trading isolation strength against infrastructure requirements.

​
Backends

The platform picks a backend in two layers: a remote sandbox-manager service (preferred), falling back to a local in-worker backend when the remote is off, unhealthy, or unreachable.

syd → gVisor (remote, default)

The remote sandbox manager runs each sandbox as a gVisor (runsc) container — a user-space kernel that intercepts syscalls, with OverlayFS and a jailed network namespace. Strong isolation; runs in Docker / Cloud Run / Kubernetes.

syd → MicroVM (remote)

The remote manager can instead run each sandbox as a full cloud-hypervisor micro-VM. The strongest isolation, but requires KVM — bare-metal or nested-virtualization hosts only (not Docker).

deno (local, default fallback)

An in-process Deno sandbox with a SQLite-backed filesystem. No Docker, no separate service — good for local dev and lightweight deployments.

subprocess / none (local)

subprocess runs code in a worker-local Python subprocess (least isolation — dev only). none disables local execution entirely.
subprocess provides no real isolation — untrusted code runs with the worker’s privileges. Use it only in trusted local development. For any shared or production deployment, run the remote sandbox manager (gVisor or MicroVM).

​
Choosing a backend

​
Configuration

The behavior is driven by environment variables read from the worker/backend settings:
When USE_REMOTE_SANDBOX=true but SANDBOX_MANAGER_URL is unset or the manager is unhealthy, the platform automatically falls back to LOCAL_SANDBOX_BACKEND, so code execution keeps working (with weaker isolation). Set LOCAL_SANDBOX_BACKEND=none if you’d rather fail closed.

​
Deploying the remote sandbox manager

The remote backends are served by a separate sandbox-manager service (the agentsandbox component):
  • gVisor manager — a container image bundling runsc (gVisor) and a minimal Debian rootfs; exposes an HTTP control-plane on port 8000. Deployable in Docker / Cloud Run / Kubernetes.
  • MicroVM manager — runs on a KVM-capable host using cloud-hypervisor; HTTP control-plane on port 8400.
Point the platform at it with SANDBOX_MANAGER_URL and share the ADMIN_API_KEY. Every control-plane call is authenticated with that key via the X-API-Key header, so the manager is never exposed unauthenticated.

​
Security model

Regardless of runtime, sandboxes are built to contain untrusted code:
  • Isolation — gVisor intercepts syscalls in a user-space kernel; MicroVM uses a full guest kernel. Each sandbox gets its own filesystem (OverlayFS: read-only base + per-sandbox writable layer).
  • Network jail — private/internal ranges (RFC1918) are blocked from inside the sandbox; it can NAT out to the public internet but cannot reach internal services. (This is why the SDK-in-sandbox pattern needs a publicly reachable backend URL.)
  • Ephemeral — non-persistent sandboxes are cleaned up when idle.
  • Permission-gated — the sandboxes:run permission is required to run code and is never implied by general resource access.
Related reading: the Agent Sandbox product page (how agents use it) and the Sandboxes SDK / Sandboxes API for programmatic use.