Remote Sandbox

A sandbox is a virtual machine your agent runs code in. This page explains the pieces behind it: what a sandbox is, how your agent reaches one, and what happens to it over a conversation. To give your agent a sandbox, follow Run code in a sandbox.

The pieces

1. Attach. Your agent asks the control plane for a sandbox by name, through the sandbox client in @astropods/adapter-core.
2. Start. The control plane creates the sandbox, wakes a paused one, or reuses a running one.
3. Credentials. The control plane returns the sandbox’s address and short-lived credentials for it.
4. Run. Your agent sends commands and reads and writes files directly on the sandbox.

The control plane manages a sandbox’s life. It never carries your agent’s commands or files, so running many commands does not slow down the rest of the platform.

How an agent reaches its sandbox

Every deployed agent receives an identity token as ASTRO_AUTHZ_TOKEN. The sandbox client uses it to prove which deployment is calling. A deployment can only reach its own sandboxes, and the API never takes a deployment id, so one agent cannot address another agent’s sandbox.

A few properties follow from this flow:

• Attach is safe to call on every turn. The same name always returns the same sandbox. Two calls racing for a new name end up sharing one sandbox.
• Attach returns only when the sandbox can take a command. Your first command does not race the machine’s boot.
• Credentials are short-lived and scoped to one sandbox. The client renews them on its own, so your code never handles them.
• The first attach can take a while. A new sandbox installs what your sandbox section declares before it answers. The client waits for it.

Names and conversations

A sandbox belongs to one deployment and is identified by a name your agent picks. Use the conversation or thread id as the name. Each conversation then gets its own machine and files, and a returning user finds the files they left.

Two names never share a filesystem. Two deployments never share a sandbox, even when they run the same blueprint.

Lifecycle

A sandbox moves through a small set of states. The client handles every transition, so your agent only ever calls attach and runs commands.

A sandbox has a maximum age of 8 hours. Before it reaches that age, Astropods saves its files and installed software. The next attach starts a new machine with everything carried over, so a long conversation does not notice the swap.

A sandbox suspended for an hour is removed with its files. The next attach for that name starts fresh, with your declared software installed and an empty /workspace.

Setting up the environment

The sandbox section in astropods.yml describes what a sandbox needs: languages, packages, environment variables, and setup commands. Astropods installs it on the first attach.

Astropods keeps the installed result for your account. Later sandboxes with the same declaration restore it instead of installing again, which is why only the first conversation is slow. Changing the declaration installs it once more. Setup commands run in every fresh sandbox, so each one starts with the same /workspace contents.

Isolation

A sandbox runs code your agent wrote, which may be code a user asked for. It is built to keep that code away from everything else:

• Its own machine. Each sandbox is a separate virtual machine with its own kernel, not a container sharing a kernel with your agent or other tenants.
• Outside the cluster. A sandbox has no network path to the cluster your agent runs on, or to other agents.
• No platform credentials inside. Astropods never places its own credentials in a sandbox. Saving and restoring files is done from outside the machine.
• No inbound traffic. Nothing outside can connect to a server started inside a sandbox. Your agent reaches it only through the sandbox client.
• Outbound internet. Code in a sandbox can reach the public internet, so it can clone a repository or download a package.
• Per-deployment scope. Sandbox names and limits apply to one deployment, and credentials work for one sandbox.

Files that cross into or out of a sandbox are checked at both ends, so a damaged transfer fails instead of leaving a partly written workspace.

Local development

ast project start gives your local agent a real sandbox of the same kind a deployed agent gets. It uses the sandbox section from your local astropods.yml, so a change applies on the next start. ast project stop deletes the sandboxes your local agent created.

Next steps

• Run code in a sandbox walks through giving an agent a sandbox, end to end.
• Sandbox client covers every client method, error, and limit.
• Astropods Spec, section 9 lists every field of the sandbox section.