Code Sandbox overview

The Code Sandbox is a locked-down, throwaway computer where your agent's Python code runs. This page explains what it is, when to use it, and how it compares to the equivalent products on AWS, Azure, and GCP.

What the Code Sandbox is

An AI agent sometimes decides it needs to run code, to do math, parse a file, or transform data. It should not run that code inside its own process. Code written by a model is untrusted code. It might loop forever, eat all the memory, or try to read the agent's API keys. The Code Sandbox solves this by running each snippet in a separate, disposable sandbox.

A sandbox is a small, isolated container the platform starts for you. Each one:

• runs exactly one snippet, then is destroyed — never reused,
• runs as a non-root user with no platform credentials,
• runs a data-science image: the standard library plus numpy, pandas, matplotlib, scipy, scikit-learn, sympy, openpyxl and pillow — and no way to install anything else,
• can reach nothing on the network - not even DNS name lookups,
• returns what the snippet printed (stdout, stderr, the exit code) and the files it wrote — up to 4 MB each and 16 MB per run — which are kept beside the conversation for as long as the session lives.

You never deploy, size, or manage the sandbox. It is always on; an agent uses it by listing the run_python tool, and every agent's own tool code is relocated into it automatically (see below).

The warm pool: why starts are fast

Starting a fresh sandbox takes time. So the platform keeps a small pool already started and waiting, called warm sandboxes. It aims to keep 3 of them.

When your agent runs code, the sandbox service claims one warm sandbox and runs the snippet in it. Then it destroys that sandbox and starts a replacement in the background. Your code begins in about a second, instead of waiting for a container to boot.

The 30-second mental model

Two kinds of sandboxed runs

1. Code snippets (run_python). Your agent sends Python source. The sandbox sends back three things: whatever the code printed (stdout), whatever it wrote as errors (stderr), and the exit code, a number where 0 means success. This is the common case. See Run code in the sandbox.
2. Sandboxed tool calls. When your agent calls one of your own tool functions, the platform can run that function in a one-use sandbox. That sandbox is built from the agent's own container image, which is the packaged copy of the agent and everything it needs to run. It is the same code, but with every platform credential stripped out. So code the model triggered can never read the agent's API keys or reach internal services. This happens automatically; you do not call it yourself.

When to use the sandbox

• Your agent needs to compute, parse, or transform something reliably. Language models are bad at arithmetic; Python is not.
• You want model-generated code to run somewhere it cannot touch your credentials or your network.
• You want each run to start from a clean slate, with nothing left over from the run before.

By default the sandbox itself keeps nothing: the container is destroyed after the run. What the code wrote is not lost, though — files in its working directory come back with the result and are kept beside the conversation (the Console shows a chart inline and offers a CSV as a download) until the session expires.

A stateful interpreter, per conversation

Set CODE_INTERPRETER_SESSION=true on the agent (platformctl agents env set my-agent CODE_INTERPRETER_SESSION=true) and every run_python call in one conversation runs in the same interpreter: the DataFrame you loaded in the first call is still there for the second, like notebook cells. The interpreter is a sandbox bound to the conversation's session; it is destroyed when the conversation has been idle for 15 minutes (the platform's SANDBOX_SESSION_IDLE_SECONDS), when the platform restarts the sandbox service, or when a call times out — a timed-out call restarts the interpreter and the model is told that variables were lost (files are kept). The model's tool description says which mode it is in, so it does not assume state it does not have.

Sessions are capped: two per project at a time and twenty across the platform (SANDBOX_SESSIONS_PER_PROJECT, SANDBOX_MAX_SESSIONS), because a session holds a sandbox the warm pool has to replace. Over the cap, the call fails with a 429 that says so, and the agent tells the user.

CODE_INTERPRETER_TIMEOUT_S (1–120, default 20) sets how long one run may take. The model is told the number.

How it compares

Every big cloud has somewhere to run untrusted code. Here is what AWS, Azure, and GCP offer, and where this platform differs.

Cloud	Their product	Their model	How ours differs
AWS	Amazon Bedrock AgentCore Code Interpreter	A sandbox in a micro-VM, which is a stripped-down virtual machine, with a data-science image and a session that keeps files and variables between calls.	One HTTP call, one throwaway sandbox with the standard library. Simpler, and weaker: nothing carries over between calls, and there are no packages beyond the standard library.
Azure	Azure Container Apps dynamic sessions	Prewarmed pools of sessions, isolated by Hyper-V, Microsoft's virtual-machine layer. You address a session with an identifier you choose, and it keeps state across calls.	Similar warm-pool speed, without the session: every call starts clean.
GCP	Gemini / Vertex AI code execution tool	A model feature, not a product. Gemini can write and run Python inline while it answers, with a numeric-computing image and files in and out.	run_python is an explicit tool. Your agent decides when code runs, or the model does by calling the tool. Either way you call it directly and get structured output back.

Every hosted interpreter above keeps state for a session and ships real packages, on purpose; so does ours, since the Code Interpreter rebuild: a data-science image, files out, and per-conversation sessions behind CODE_INTERPRETER_SESSION=true. What ours does not do is reach the network from model-written code — not even DNS — or let model code call the agent's tools from inside the sandbox (that "bindings" pattern is on the list, not built).

Read the complete security architecture and isolation specifications in Security and limits.

In this section

• Run code in the sandbox — using run_python from an agent, and the raw API.
• Security and limits — the security architecture, network isolation, and resource limits.
• Troubleshooting — real error messages and fixes.

Related: Agent tools · Invoke an agent