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’s sandbox integration is built on OpenSandbox , an open-source sandbox runtime that spawns short-lived Linux containers on demand. The wiring:

┌─────────────────────┐      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 container has a 30-minute TTL that can be renewed via connect_sandbox.

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 OpenSandbox controller runs alongside 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
  • Point at a managed OpenSandbox instance — anything reachable over HTTP with an API key

Once the controller is running, configure auxilia with OPEN_SANDBOX_DOMAIN (and optionally OPEN_SANDBOX_API_KEY). The Setup page walks through it.

Next

n8nSetup