# How do I make agent computers start instantly? > Prepare a Computer once, snapshot it, and keep a warm pool of ready copies, so a new Computer can start in under a second. Snapshot templates let you promote or roll back. - Source: Sanbox knowledge base, by Sanlabs GmbH - URL: https://sanbox.cloud/kb/build/warm-pools-and-snapshot-templates/ - Type: how-to - Section: Building agent products - Language: en - Published: 2026-11-06 - Updated: 2026-11-06 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 ```text 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? | | What it is | How you start a Computer from it | |---|---|---| | Snapshot | A named copy of a stopped Computer: files, installed packages, saved configuration | `sanbox run --snapshot ` | | Warm pool | Up to five ready Computers from a snapshot or a snapshot template | Automatically, when a matching run starts | | Snapshot template | A template whose runs start as copies of a snapshot, with its own network policy, inbound rules, Secret Proxies and model connection | `sanbox run --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 ` or `sanbox exec`. ### 2. Stop it ```bash sanbox runs stop --wait --json ``` ### 3. Take a snapshot ```bash sanbox snapshots create --run --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 ` and `sanbox snapshots delete --yes` to manage them. ### 4. Start Computers from it ```bash sanbox run --snapshot research-workspace --external-run-id --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 ```bash 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: ```bash 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 ` and switch the snapshot behind it without changing code. It needs CLI 0.0.23 or later. ```bash sanbox templates create --name "App dev" --snapshot research-workspace \ --model-provider --network-policy dev-policy.json --json sanbox pools create --template --name app-dev-pool --size 2 sanbox run --template --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: ```bash sanbox templates update --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?](https://sanbox.cloud/kb/build/one-persistent-computer-per-user/) - [How do I try three approaches from the same starting point?](https://sanbox.cloud/kb/parallel-work/fork-a-computer-to-try-several-approaches/) - [How do I run Docker Compose inside an AI agent's sandbox?](https://sanbox.cloud/kb/parallel-work/docker-compose-inside-an-agent-computer/) - [What survives when an agent's computer stops?](https://sanbox.cloud/kb/agent-computers/what-survives-a-stop/) ## Next step Talk to us at sales@sanlabs.ai. Sanlabs' forward-deployed engineers build agent use cases with your team, with experience in aviation, pharmaceuticals, supply chain and logistics, and internal admin workflows. How we work: https://sanbox.cloud/kb/teams/forward-deployed-engineering.md Existing customers can use Sanbox from a coding agent: install the CLI with `npm install -g @sanlabs/sanbox-cli@latest`, sign in with `sanbox login`, then run `sanbox skill` for the full agent guide.