Skip to Content
Deploy & ConfigureSandboxOverview

Sandbox — Overview

The sandbox gives an agent a private, isolated Linux environment for executing code, reading and writing files, searching, and running shell commands. It turns any agent into a lightweight data-analysis or scripting agent without handing it access to the host.

This page is the operator’s view — what the sandbox is, how it’s architected, and what you need to run. For how an agent author enables and uses the sandbox inside an agent, see Using the sandbox.

Why a sandbox

MCP servers cover most structured actions (query HubSpot, search Sentry, open a PR in GitHub). But some tasks don’t fit that shape — they need a scratch environment with a filesystem and a Python shell:

  • Analyze a CSV the user uploads and produce a chart
  • Write, lint, and run a Python script against live data
  • Iterate on a SQL query using bq or psql
  • Transform a payload with jq before feeding it to another tool

The sandbox provides that environment and exposes it to the agent as a toolset.

How it works

auxilia supports two sandbox providers, selected with the SANDBOX_PROVIDER environment variable:

  • opensandbox (default) — OpenSandbox , an open-source sandbox runtime that spawns short-lived Linux containers on demand. You run the controller yourself, next to the backend.
  • cloudrun — Google Cloud Run sandboxes  (public preview), reached through a dedicated sandbox gateway Cloud Run service. Nothing to host beyond that one service — see Cloud Run Sandboxes.

Whichever provider you pick, the agent sees the exact same toolset (create_sandbox / connect_sandbox + file ops) — the provider only changes where the container runs.

With OpenSandbox, the wiring looks like this:

┌─────────────────────┐      create_sandbox()      ┌────────────────────┐
│  Agent (LangGraph)  │ ───────────────────────▶   │   OpenSandbox      │
│                     │ ◀───── sandbox_id ──────── │   controller       │
└─────────────────────┘                            └─────────┬──────────┘
         │                                                   │
         │  execute("python script.py")                      │
         │  read_file("/tmp/out.json")                       │
         │  …                                                ▼
         │                                        ┌──────────────────────┐
         │                                        │   Container          │
         └──────────────────────────────────────▶ │   (python:3.12-slim) │
                                                  └──────────────────────┘

The sandbox is lazy: it is not created when an agent starts. The LLM decides when (and whether) to call create_sandbox, and only then does a container come up. A default OpenSandbox container has a 30-minute TTL that can be renewed via connect_sandbox; Cloud Run sandboxes have no TTL and instead persist between turns via GCS snapshots.

Inside a conversation, the agent can create one sandbox, keep reusing it across turns, and reconnect to it after a browser refresh.

What you need to run it

The sandbox runtime runs outside the auxilia backend. auxilia is a client of it — the backend never executes shell commands itself.

You can either:

  • Self-host OpenSandbox — run the controller in a container on the same host, in the same VPC, or on Kubernetes, then configure auxilia with OPEN_SANDBOX_DOMAIN (and optionally OPEN_SANDBOX_API_KEY). The Setup page walks through it.
  • Point at a managed OpenSandbox instance — anything reachable over HTTP with an API key
  • Use Cloud Run sandboxes — deploy the sandbox-gateway service on Google Cloud Run and set SANDBOX_PROVIDER=cloudrun. See Cloud Run Sandboxes.

Next

  • Setup — pick a provider, run OpenSandbox and point auxilia at it
  • Cloud Run Sandboxes — deploy the sandbox gateway and use Google Cloud Run sandboxes
  • Security — isolation, volume mounts, timeouts
  • Using the sandbox in an agent — the agent-author side: enabling the toggle and the toolset the LLM sees
n8nSetup