Running an agent's code in a sandbox

The last post gave the agent the ability to write code. This post gives it a safe place to run it, because running model-generated code on your own machine is not something you do twice.

A sandbox is an isolated environment: separated from the host, capped on resources, and thrown away when you are done. The agent writes code, the sandbox runs it, and the result comes back.

Why the code needs isolating

Code from a model is unpredictable where a registered tool is fixed. A tool does one known thing. Model-written code does whatever the model wrote, and the model can be wrong or steered.

Three failure modes make the point, and none of them requires bad intent.

• A wrong path. The model means to clean a temp folder and writes os.remove against the wrong directory. On your host, that is your files.
• A runaway. An infinite loop, or code that allocates memory without bound, freezes the machine it runs on.
• Something worse. A model steered by injected input can be led to write code that reads your secrets or reaches out to the network. This is not hypothetical, and the security series treats it directly.

A sandbox is the answer to all three, which is why code execution and sandboxing are one feature, not two.

What a sandbox actually gives you

Isolation buys three concrete protections.

Security through isolation. The sandbox cannot see the host's sensitive files: no ~/.ssh keys, no /etc/passwd, no API keys sitting in the host's environment. You can tighten it further by limiting which network domains the sandbox may reach.

Resource limits. CPU, memory and wall-clock time are capped. An infinite loop hits the timeout and is killed; memory-hungry code stops at the limit. The host is never dragged down by what runs inside.

Recoverability. If something goes wrong inside, you discard the sandbox and make a fresh one. Deleted files, a corrupted environment, none of it matters, because the sandbox was disposable from the start.

A sandbox isolates from the host, caps resources, and is disposable. The host is never at risk.

Options, from heavy to hosted

There is more than one way to get a sandbox, trading control against effort.

You can manage your own with Docker containers, which gives full control and all the operational work that comes with it. Or you can use a hosted sandbox service, which hands you an isolated environment over an API and manages the isolation for you. This post uses a hosted service to keep the focus on the agent, and the choice does not change the shape of the integration.

Connecting the sandbox as a tool

The agent reaches the sandbox through one tool: give it code, get back the output. It is an ordinary tool, the same shape as every other in this series.

@tool
def execute_python(code: str) -> str:
    """Run Python code in the sandbox and return its stdout and any error."""
    result = sandbox.run_code(code)          # runs in isolation, not on the host
    return result.stdout + result.stderr

That is the whole interface from the agent's side. The agent writes a program, calls execute_python, and reads what came back, exactly as it reads any tool result. Everything dangerous happens inside the sandbox, behind the boundary; the agent only ever sees the output.

Watching it run

Give the agent the ten-file task from the last post and it writes and runs the code itself.

Action:  execute_python('''
           import glob
           total = 0
           for path in glob.glob("*.txt"):
               total += open(path).read().count("error")
           print(f"{total} error lines across {len(glob.glob('*.txt'))} files")
         ''')
Observe: 47 error lines across 10 files

One tool call did the work of eleven. The files were read inside the sandbox, never entering the agent's context, and only the one-line summary came back. The efficiency argument from the last post is now real, and it is safe, because the reading happened somewhere the agent could not touch the host.

The agent writes code, the sandbox runs it in isolation, and only the result crosses back.

What to take from this

• Model-written code is unpredictable, so it runs in a sandbox: an environment isolated from the host, resource-limited, and disposable.
• Isolation gives three protections: the host's secrets and files are hidden, runaways hit resource limits, and a broken sandbox is thrown away and remade.
• The agent reaches the sandbox through one ordinary tool. It writes code, the sandbox runs it, and only the output crosses back. Everything dangerous stays behind the boundary.

A sandbox runs raw code well. Some of that code re-implements tools you already built, though, and re-writing them each time is waste. The next post ports your existing tools into the sandbox so the agent can call them from code.