Guide

What is an AI agent sandbox, and how do code sandbox APIs work?

Short answer: An AI agent sandbox is an isolated VM or container where an agent can run code, read and write files, and see the output, without touching the machine it runs on. Sandbox APIs offer one-shot runs or long-lived sessions, stream output as it arrives, and often control network access. Isolation protects the host from the guest's code. It does not hide the guest's data from whoever runs the host.

AI agents that write code need somewhere to run it. Running it on your laptop or server is risky: generated code can delete files, leak keys or loop forever. A sandbox gives the agent its own disposable machine. This guide covers what sandboxes are, the patterns most sandbox APIs share, and how Smarty Pants CPU jobs and workspaces work today.

What is an AI agent sandbox?

It is an isolated VM or container where an agent can run commands, work with files and read the output. Whatever the code does stays inside the sandbox, and the sandbox can be thrown away after.

The isolation layer varies. Modal runs sandboxes on gVisor, a container runtime, or on a VM runtime with its own Linux kernel. E2B describes its sandbox as an “isolated Linux VM for your agent.” Firecracker, a microVM monitor used for multi-tenant services, treats the guest as hostile from the start: its design document says “all vCPU threads are considered to be running malicious code as soon as they have been started.”

What do sandbox APIs usually offer?

Most offer the same building blocks: run a command, move files, stream output, control the network and, on some, save state.

Feature What it does Example
Run commands Start a program in the sandbox and get its exit code and output Modal sb.exec(...) with an optional timeout
Files Write files in, read results out Smarty Pants workspace /files requests
Streamed output Send stdout and stderr while the program runs E2B onStdout / onStderr callbacks
Snapshots Save the sandbox’s state and start new ones from it E2B snapshots capture filesystem and memory; Modal filesystem snapshots
Egress control Turn network off or allow only some destinations E2B can disable internet or use allow and deny lists
Lifetime limits End the sandbox after a time or idle period Smarty Pants workspaces: 30 minutes, or 10 minutes idle

Defaults differ. E2B’s internet access page says “Every sandbox has outbound access to the internet by default,” and lets you turn it off. Check each provider’s default before running untrusted code.

One-shot run or long-lived session?

Use a one-shot run for a single calculation; use a session when the agent needs to build on earlier steps.

  • One-shot run. Send code, get output, and the environment is wiped. Nothing carries over, which keeps runs simple and independent.
  • Long-lived session. One environment stays open for many commands. The agent can write a file, run a script against it and read the result. Sessions end on a time limit or an idle limit, so the agent has to plan for that.

How does streamed output work?

The sandbox sends output as the program prints it, so an agent can watch progress instead of waiting. Some APIs push output through callbacks, as E2B does. Others let you poll by byte offset: you ask for output from a position, receive new text and a next offset, and repeat until the API says the command is done. Polling by offset never repeats text you already have, and you can resume after a dropped connection.

Why not retry sandbox commands automatically?

Because a failed command may already have changed something. A script can write half a file, or a job can finish while the response is lost. Rerunning it blindly can double the effect. Before retrying, check the sandbox state, or send an idempotency key so the service can recognize a repeat. The Smarty Pants Python starter kit sends an idempotencyKey with each CPU job.

What is available today on Smarty Pants?

CPU jobs and workspace sessions are available today. Both run in a sealed Linux VM on an Apple Silicon Mac, and both are open to Smarty Pants’ own account first. Other accounts get a 403 error until they open. Details from the agent docs:

CPU jobs (one-shot)

  • A short Python, JavaScript or shell program runs in a sealed Linux (ARM64) VM: no network, no disk, wiped after.
  • Up to 30 seconds per job and up to 4 KB of output.
  • Output streams while it runs: GET /v1/cpu/jobs/{id}/output?stdoutOffset=0&stderrOffset=0 returns what it has printed so far. Pass back each stream’s nextOffset until done is true.
  • Listed price: $0.00405 per vCPU-hour plus $0.002025 per GB-hour, about $0.00007 for a 20-second job at the default size of 2 vCPU and 2 GB of memory.

More on the CPU jobs page.

Workspaces (sessions)

  • One sealed VM stays open for many commands and files. Files live until the workspace ends; nothing is kept after.
  • Limits: 30 minutes per workspace, 10 minutes idle, 10 minutes per command, files up to 8 KB, 4 KB of output per stream.
  • The Mac’s owner comes first. If they come back, the workspace ends within 5 seconds.
  • API: POST /v1/cpu/sessions, then /exec and /files; end it with DELETE /v1/cpu/sessions/{id}.
  • Not charged while it is tested on Smarty Pants’ own account.

More on Agent workspaces and Workspace sessions.

What is Planned for Smarty Pants workspaces?

These features are Planned and not available.

Feature Status What it will let you do
Snapshots and recovery Planned Save a workspace and continue it on another Mac if its Mac goes away
Model calls from workspaces Planned Call Smarty Pants models from inside a workspace with a key limited to that workspace and a spending budget
Fleets and browser work Planned Run several sessions at once, and use a web browser in a workspace
Always-on agents Planned Keep an agent working for days
Internet access Planned Reach the internet from inside a workspace
CLI and SDK Planned Tools for paid developer use

Who does sandbox isolation protect?

It protects the host from the guest, not the guest from the host. That is true for any sandbox. On Smarty Pants, VM isolation protects the Mac’s owner from guest code. It does not keep the guest’s files or memory confidential from the Mac’s owner, who controls the hardware.

So treat a Smarty Pants workspace like any machine you don’t control: don’t put API keys, customer data or other secrets in it. If your agent handles sensitive data, run its sandbox on hardware you or a provider you trust controls.

Frequently asked questions

What is an AI agent sandbox?

It is an isolated VM or container where an AI agent can run code it wrote, work with files and read the results. If the code misbehaves, the damage stays inside the sandbox.

What is the difference between a one-shot run and a session?

A one-shot run starts a fresh environment, runs one program, returns the output and is wiped. A session keeps one environment open so an agent can run many commands and keep files between them.

Does a sandbox keep my code and data private from the host?

No. VM isolation protects the host from the guest's code. Whoever runs the host machine is not kept out of the guest's files or memory, so don't put secrets in a sandbox on hardware you don't trust.

Can I use Smarty Pants CPU jobs today?

Not yet for most people. Smarty Pants runs CPU jobs and workspaces on its own account first, and other accounts get a 403 error until they open.

Do Smarty Pants sandboxes have internet access?

No. CPU jobs and workspace sessions run with no network today. Internet access from a workspace is Planned and not available.

Should an agent retry a failed sandbox command automatically?

Only when rerunning is safe. A command can have changed files before it failed, so check state first, or use an idempotency key where the API offers one.

Sources

  1. Firecracker: Design document (threat model)
  2. E2B Docs: Sandbox
  3. E2B Docs: Streaming command output
  4. E2B Docs: Snapshots
  5. E2B Docs: Internet access
  6. Modal Docs: Sandboxes
  7. Smarty Pants: Agent kit and docs
  8. Smarty Pants: Python starter kit

Try a pinned open model on real Macs.

See every model, its listed price and the code to call it. Smarty Pants works with the OpenAI SDK you already use: change the base URL and the key.

Requests run on Macs owned by other people. Owners agree not to read requests and the app doesn't show them, but a serving Mac decrypts each request in memory to answer it, so that is a rule and a design, not a technical guarantee. Don't send sensitive data on the general network.