Sandbox

Use the sandbox config in your agent definition to define the default filesystem, template build, working directory, and per-sandbox setup for every sandbox created from a deployed agent.

How sandbox setup works

On deploy, the CLI bundles your agent and can optionally upload a template/ directory next to your agent entry point. You only need this folder if you want to upload files with the deployment.
The platform builds a deployment-specific sandbox template. apt, files, cwd, and build are applied here. Files from your sandbox config are copied before build commands run. Every new sandbox later starts from this built template.
When a sandbox is created later (for example, on a new chat), it starts from that built template and then runs setup.
During chat execution, the agent runtime uses cwd as its working directory. If you omit it, the default is /home/user/workspace.

Runtime locality and isolation

E2B still remains the outer sandbox. When a chat starts, your tools and MCP servers run inside that sandbox instead of on a separate remote worker. The agent process itself runs in an isolated execution layer inside the same sandbox.

This is why dashboard env vars can be available to tools and runtime code without showing up as ordinary env vars to the agent itself.

Example

A typical sandbox config installs system packages, adds project files, runs dependency installation at deploy time, and keeps a small setup step for each sandbox instance.

agents/support-agent/index.ts

import { agent, Sandbox } from "@21st-sdk/agent"

const REFUND_SKILL = `# Refunds

Always verify the order ID before issuing a refund.`

export default agent({
  runtime: "claude-code",
  model: "claude-sonnet-4-6",
  systemPrompt: "You are a helpful support agent.",
  sandbox: Sandbox({
    apt: ["ffmpeg", "poppler-utils"],
    cwd: "/home/user/workspace",
    files: {
      "/home/user/workspace/.claude/skills/refunds/SKILL.md": REFUND_SKILL,
    },
    build: [
      "corepack enable",
      "pnpm install",
    ],
    setup: [
      "node scripts/session-bootstrap.js",
    ],
  }),
})

Field reference

Field	Current behavior
`apt`	Installs system packages while building the deployment template.
`build`	Runs shell commands during template build after template files and sandbox files have been copied. Use this for static work that should be baked into the template.
`setup`	Runs shell commands each time a new sandbox is created, for example on a new chat creation. Use this for dynamic work that should happen per sandbox.
`files`	Copies files into the deployment template before build commands run.
`cwd`	Creates and uses this directory for build commands, setup commands, and runtime agent execution. If omitted, `/home/user/workspace` is used.

When to use build vs setup

build

Runs once while the deployment template is being built. Every new sandbox starts from the result, so this is the right place for heavy or static work that does not need to change between sandboxes.

Install dependencies
Compile assets or generate code
Prepare files that should already exist in every sandbox

setup

Runs each time a sandbox is created, for example on a new chat creation. Use it for dynamic steps that should happen at sandbox creation time rather than being baked into the template.

Fetch an external file that changes frequently
Generate fresh local state or config for this sandbox
Start a background helper or internal server for this sandbox

Using a template directory

The template/ folder is optional. Use it only when you want to upload files with the deployment. When it exists, the CLI will include a sibling template/ directory in the deploy payload and unpack it inside the root path /home/user/workspace as-is.

project structure

agents/support-agent/
├── index.ts
└── template/
    ├── .claude/
    │   └── skills/
    │       └── refunds/
    │           └── SKILL.md
    └── repo/
        ├── README.md
        ├── notes/
        │   └── checklist.md
        └── data/
            └── sample.json

During deploy, that archive is extracted into /home/user/workspace before build runs, so keep most of your own files inside a subdirectory like repo/. cwd changes where commands run, not where the template archive is unpacked.

Filesystem conventions

The sandbox root is /home/user/workspace. Claude project settings live in /home/user/workspace/.claude.

If you want skills or MCP config in the sandbox, you need to place those files yourself through files or your template. Files from your template directory and sandbox file config go directly into /home/user/workspace. The platform does not manage them for you.

Put skills in /home/user/workspace/.claude/skills/<name>/SKILL.md. See Skills.
Put MCP config in a sibling .mcp.json file next to your agent entrypoint, not in /home/user/workspace. See Tools and MCPs.

What Sandbox does not cover

Environment variables are not part of the sandbox config. Use the dashboard env vars or pass envs when you create a runtime sandbox from the Server SDK.

Dashboard env vars are loaded into the runtime and tool layer inside the sandbox, but they are not exposed to the isolated agent process as ordinary env vars. From tool code, change sandbox files with local fs APIs inside the runtime. Use AgentClient from your own service when you need to read or change sandbox state remotely.