> For the complete documentation index, see [llms.txt](/llms.txt). > A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt). --- title: Use sandboxes with agents description: Give an agent an isolated workspace where it can write files, read files, list files, and execute code. last_verified: 2026-06-23 --- A **sandbox** is an isolated workspace attached to an **[agent](/docs/build/agents.md)**. The agent can write files, read files, list directories, and execute code without running generated code in your worker process. Use sandboxes when an agent needs to inspect code, create scripts, run tests, or verify calculations before it answers. ## Attach a sandbox Pass `Sandbox()` to the agent constructor. AGNT5 creates the provider sandbox on first use, keeps the workspace available for the duration of the run, and closes it when the run ends. **Python:** ```python from agnt5 import Agent, Sandbox agent = Agent( name="coder", model="openai/gpt-4o-mini", instructions=( "Use the sandbox workspace to write files, inspect files, " "and run code before you return an answer." ), sandbox=Sandbox(), ) result = await agent.run( "Create answer.py, make it print 6 * 7 as JSON, run it, and show the output." ) print(result.output) ``` **TypeScript:** ```ts const agent = new Agent({ name: 'coder', model: LM.openai(), modelName: 'openai/gpt-4o-mini', instructions: 'Use the sandbox workspace to write files, inspect files, and run code before you return an answer.', sandbox: new Sandbox(), }); const result = await agent.run( 'Create answer.py, make it print 6 * 7 as JSON, run it, and show the output.' ); console.log(result.output); ``` The agent can write files, read files, list files, and execute code automatically. You still pass custom tools through `tools=[...]` or `tools: [...]` when the agent needs other capabilities. ## Choose a provider `Sandbox()` auto-detects the first configured provider from environment variables. Pass a provider name to use a specific one. **Python:** ```python from agnt5 import Agent, Sandbox agent = Agent( name="daytona_coder", model="openai/gpt-4o-mini", instructions="Use the Daytona sandbox for code and file work.", sandbox=Sandbox(provider="daytona"), ) ``` **TypeScript:** ```ts const agent = new Agent({ name: 'daytona-coder', model: LM.openai(), modelName: 'openai/gpt-4o-mini', instructions: 'Use the Daytona sandbox for code and file work.', sandbox: new Sandbox({ provider: 'daytona' }), }); ``` Common provider names are `e2b`, `daytona`, `vercel`, `northflank`, and `together`. Configure the provider credentials before running the agent. See [Sandbox providers](/docs/integrations/sandbox-providers.md) for the required environment variables. > **Together limitation:** The Together provider only supports Python code execution. Shell commands (`run_command`) are not available, and sessions expire automatically after 60 minutes and cannot be destroyed early. `auto_destroy` / `autoDestroy` is ignored. ## Configure the sandbox Beyond `provider`, the `Sandbox` constructor accepts options to control the environment, resources, and lifetime. **Python:** ```python sandbox = Sandbox( provider="e2b", template="my-custom-image", # specific sandbox image or snapshot env={"OPENAI_API_KEY": "sk-..."}, # environment variables inside the sandbox timeout_secs=600, # sandbox lifetime in seconds (default: 300) cpu_cores=2, # CPU cores to allocate memory_mib=2048, # memory in MiB to allocate ) ``` **TypeScript:** ```ts const sandbox = new Sandbox({ provider: 'e2b', template: 'my-custom-image', // specific sandbox image or snapshot env: { OPENAI_API_KEY: 'sk-...' }, // environment variables inside the sandbox timeoutSecs: 600, // sandbox lifetime in seconds cpuCores: 2, // CPU cores to allocate memoryMib: 2048, // memory in MiB to allocate }); ``` Not all providers support every option. `template`, `cpu_cores`/`cpuCores`, and `memory_mib`/`memoryMib` are passed through to the provider and have no effect when the provider does not support them. ## Use the sandbox from custom tools Custom tools can use the same sandbox through `ctx.sandbox`. This lets you add project-specific behavior while sharing the agent's workspace. **Python:** ```python from agnt5 import Agent, Sandbox, tool from agnt5.context import Context @tool async def count_lines(ctx: Context, path: str) -> dict: """Count lines in a sandbox file. Args: path: Path to the file inside the sandbox workspace. """ content = await ctx.sandbox.read_file(path) text = content.content.decode("utf-8") return {"path": path, "lines": len(text.splitlines())} agent = Agent( name="code_reviewer", model="openai/gpt-4o-mini", instructions="Use the sandbox and count_lines tool to inspect generated files.", sandbox=Sandbox(provider="e2b"), tools=[count_lines], ) ``` **TypeScript:** ```ts const countLines = tool( 'count_lines', { description: 'Count lines in a sandbox file.', inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Path to the file inside the sandbox workspace.' }, }, required: ['path'], }, }, async (ctx, args) => { if (!ctx.sandbox) throw new Error('No sandbox is attached to this agent.'); const file = await ctx.sandbox.readFile(args.path); return { path: args.path, lines: file.content.toString('utf-8').split('\n').length, }; } ); const agent = new Agent({ name: 'code-reviewer', model: LM.openai(), modelName: 'openai/gpt-4o-mini', instructions: 'Use the sandbox and count_lines tool to inspect generated files.', sandbox: new Sandbox({ provider: 'e2b' }), tools: [countLines], }); ``` ## Run shell commands The Python SDK exposes `run_command()` on the sandbox for running arbitrary shell commands, not just code. Use it from a custom tool when you need to install packages, run build steps, or execute scripts. **Python:** ```python from agnt5 import Agent, Sandbox, tool from agnt5.context import Context @tool async def install_and_run(ctx: Context, package: str, script: str) -> dict: """Install a package and run a script inside the sandbox.""" install = await ctx.sandbox.run_command("pip", args=["install", package]) run = await ctx.sandbox.run_command("python", args=[script]) return {"install": install.stdout, "output": run.stdout, "error": run.stderr} agent = Agent( name="builder", model="openai/gpt-4o-mini", instructions="Use install_and_run to set up dependencies and execute scripts.", sandbox=Sandbox(provider="e2b"), tools=[install_and_run], ) ``` `run_command` accepts `args`, `working_dir`, `env`, and `timeout_ms`. It returns `stdout`, `stderr`, and `exit_code`. A streaming variant `run_command_stream` is also available for long-running commands. > **Note:** `run_command` is Python-only. TypeScript supports `executeCode` for running code but does not have a built-in shell command method. See [Sandbox providers](/docs/integrations/sandbox-providers.md) for provider-specific capabilities. ## Control lifecycle By default, AGNT5 owns the sandbox lifecycle for the agent run: - **Create**: the provider sandbox is created on first use. - **Share**: file and execution state stays available across sandbox calls in the run. - **Close**: the provider sandbox is destroyed when the agent run finishes. Set `auto_destroy=False` in Python or `autoDestroy: false` in TypeScript when you need to keep the provider sandbox alive after the run for debugging. **Python:** ```python sandbox = Sandbox(provider="e2b", auto_destroy=False) ``` **TypeScript:** ```ts const sandbox = new Sandbox({ provider: 'e2b', autoDestroy: false }); ``` > **Warning:** Leaving provider sandboxes running incurs ongoing provider cost and leaves your files accessible in the provider environment until the session expires. Use `auto_destroy=False` only for short debugging sessions. ## Validate your provider setup Use the `sandbox-smoke` template when you want to confirm that your credentials and provider are working correctly before building. ```bash agnt5 create --template python/sandbox-smoke sandbox-smoke cd sandbox-smoke cp .env.example .env agnt5 --env-file .env dev ``` Run the lifecycle check after the worker is connected: ```bash agnt5 --env-file .env run sandbox_lifecycle_check \ --input '{"provider": "e2b", "code": "print(6 * 7)", "language": "python"}' ``` The smoke template also includes checks for file write, file read, file list, direct code execution, and an agent that uses the sandbox through its built-in tools. ## Next steps - [Sandbox providers](/docs/integrations/sandbox-providers.md): configure E2B, Daytona, Vercel, Northflank, or Together credentials. - [Agents](/docs/build/agents.md): configure agent loops, tools, handoffs, and iteration limits. - [Tools](/docs/build/tools.md): add custom tools that share the agent's sandbox workspace. - [Local development](/docs/build/local-development.md): run a worker locally with `agnt5 dev`.