How do I make agent computers start instantly?

Do the slow setup once and start every new computer from the result, with a few copies already running and waiting. In Sanbox, you prepare a Computer, stop it and take a snapshot; a warm pool keeps up to five ready Computers from that snapshot, so a new one can start in under a second instead of installing everything again. A template built from the snapshot gives your app one stable ID to start from, and lets you promote a new snapshot or roll back to an old one.

Run this with your agent

Read https://sanbox.cloud/kb/build/warm-pools-and-snapshot-templates.md and follow it to set up a snapshot and a warm pool.
If the Sanbox CLI is missing, install it with `npm install -g @sanlabs/sanbox-cli@latest`
and sign in with `sanbox login`. Show me each command before you create, stop or delete a Computer.

Snapshot, warm pool or snapshot template?

Snapshots work for stopped, writable OpenCode, Browser, Docker and Hermes Computers. A Docker Computer's snapshot keeps its images, containers and volumes. Capturing snapshots and managing pools needs an organisation admin or owner. Developers can start and operate Computers from them.

Steps

1. Prepare a Computer

Start a Computer and do the slow work: clone repositories, install packages, pull images, load test data. Use the console terminal, sanbox ssh <run-id> or sanbox exec.

2. Stop it

sanbox runs stop <run-id> --wait --json

3. Take a snapshot

sanbox snapshots create --run <run-id> --name research-workspace --wait

Names are 1 to 48 lowercase letters, digits and single hyphens, starting with a letter. They can't be changed, and they stay reserved after deletion. Use sanbox snapshots list, sanbox snapshots get <name> and sanbox snapshots delete <name> --yes to manage them.

4. Start Computers from it

sanbox run --snapshot research-workspace --external-run-id <retry-key> --json

Each run is an independent copy. Snapshot starts accept no launch overrides, so the snapshot's saved settings decide the agent, model and disk size. Reuse the same --external-run-id after a lost response.

5. Keep a warm pool

sanbox pools create --snapshot research-workspace --name research-pool --size 2

Now sanbox run --snapshot research-workspace takes a ready Computer when there is one, and starts one cold when there isn't. Change or drain the pool with:

sanbox pools resize research-pool --size 0
sanbox pools delete research-pool --yes

--size goes from 0 to 5, and 0 drains unused Computers. Deleting a pool keeps the Computers it already handed out, and the snapshot.

Build a template on the snapshot

A snapshot template lets your app start Computers with sanbox run --template <template-id> and switch the snapshot behind it without changing code. It needs CLI 0.0.23 or later.

sanbox templates create --name "App dev" --snapshot research-workspace \
  --model-provider <provider-id> --network-policy dev-policy.json --json
sanbox pools create --template <template-id> --name app-dev-pool --size 2
sanbox run --template <template-id> --json

• The snapshot fixes the agent, its settings, the model and allowed models, the runtime image, the disk size and the environment variables. Setting any of them on the template returns snapshot_template_setting_locked.
• The template sets egress, inbound rules, Secret Proxy grants and the model provider connection. The connection must be the snapshot's kind of provider and list the snapshot's models. Anything you leave out comes from the snapshot's source run, including its Secret Proxy grants.
• Runs take no task or model override. They accept --external-run-id.
• A pool belongs to its template. A snapshot's own pool serves only sanbox run --snapshot, and a template's pool is deleted with the template.

You can build several templates on one snapshot, for example one per environment of your app, each with its own model connection and network policy.

How do I promote or roll back?

Prepare a better Computer, snapshot it under a new name, and point the template at it:

sanbox templates update <template-id> --snapshot research-workspace-v2 --json

Any change to the template replaces the pool's unused Computers, so a promotion never hands out the old image. To roll back, point it at the old snapshot again. Computers that are already running keep what they started with. A snapshot can't be deleted while a template uses it, which returns snapshot_in_use.

If the template changes while a run or pool is being created, the API returns template_changed (409) and creates nothing. Retry with the same --external-run-id or --request-key.

What should I know about warm pools?

• They use capacity. Ready Computers consume ordinary capacity in your organisation while they wait.
• They aren't frozen. A waiting Computer may have advanced a little through ordinary background activity.
• They fall back to cold starts. When the pool is empty, a run starts cold.
• Assigned Computers never return to the pool. Once a Computer is handed out, it's never recycled.
• A run with its own environment starts cold. Through the API, a run on a snapshot template can set environment variables; such a run skips the pool.

What this doesn't do

• No running processes. A snapshot keeps the disk, not RAM. Services start again in each new Computer, and Docker containers come back only with a restart policy.
• No credentials from a previous boot. Docker registry logins aren't saved in snapshots.
• No bound channels. As with forks, runs with email, Telegram or delegated Supabase bindings can't be snapshotted.
• No new ports on old snapshots. Computers started with sanbox run --snapshot keep the inbound ports of the Computer the snapshot came from.
• No more than five ready Computers per pool.

Related

• How do I give each of my users their own persistent agent computer?
• How do I try three approaches from the same starting point?
• How do I run Docker Compose inside an AI agent's sandbox?
• What survives when an agent's computer stops?