--- title: "A fleet of sandboxes · intentic docs" description: "Connect one sandbox to your account so its agent can create the others: a provisioning token, a card in chat for every create, and sandbox.toml as the unit of work." url: "https://intentic.dev/docs/fleet/" updated: "2026-09-22" --- Agent Orchestration # A fleet of sandboxes A specialized agent is a sandbox of its own, and a team of them is several. Connect one sandbox to your account and its agent can create the others — on your computers, from a file you review, asking you in chat every time. **On this page (7 sections)** - [Why this exists](#why-this-exists) - [Connecting it](#connecting-it) - [What the agent runs](#what-the-agent-runs) - [The order is the safeguard](#the-order-is-the-safeguard) - [What it will not do](#what-it-will-not-do) - [A sandbox as a file](#a-sandbox-as-a-file) - [Another sandbox, or another persona?](#another-sandbox-or-another-persona) ## Why this exists Everything else an agent needs, it can ask for: a connector, a device, a secret, a package in its image. A second**sandbox** was the exception. Creating one has always meant a browser — a page, a name, a setup code copied into a terminal — so an agent that decided the work needed its own machine could only ask you to go and do it. The Sandbox fleet capability closes that. It is one credential, held by the daemon, that lets a sandbox create sandboxes on the account that owns it. ## Connecting it 1. Mint a provisioning token at **Settings → Tokens**. It is shown once; only its digest is stored. 2. In the sandbox that should hold it, add the **Sandbox fleet** capability and paste the token in. That is the whole setup, and it is deliberately one sandbox rather than a switch on your account. The box you connect is the one that can provision; every other sandbox you own is unchanged. An agent that needs it and does not have it asks the ordinary way: ```bash capabilities request fleet --why 'so I can bring up the reviewer sandbox we planned' ``` ## What the agent runs ```bash sandboxes ls sandboxes create reviewer --why 'somewhere to run the nightly review off this box' sandboxes create storefront --on build-rig --definition ./team/storefront.sandbox.toml ``` `create` holds its connection through both slow halves — you deciding, then the machine pulling an image and starting a container. Every line the machine printed comes back with the answer, so a create that fails reads like the setup wizard does rather than like a boolean. ## The order is the safeguard | Step | What happens | | --- | --- | | **The card** | Your chat asks, naming the sandbox and the machine it would run on. Nothing has been created yet. | | **The claim** | A yes mints the sandbox's row and one short-lived, single-use setup code. | | **The build** | That code goes straight to the machine, which builds the container with `ic`, the same way every other sandbox on it was built. | Because the card comes first, a no costs the account nothing at all: no row, no code, nothing left to expire. There is no auto-approve band here and no standing allowance — unlike a payment, creating a sandbox is rare enough that every one of them is worth a click. ## What it will not do - **It never provisions hosted machines.** A sandbox made this way runs on a computer you have connected as a device. Nothing here can spend your hosted plan. - **It creates; it does not destroy.** There is no remove verb. Deleting a sandbox stays yours, in your own UI. - **It carries no credentials into the new box.** A definition names capabilities and secrets; their values are never in it, and you connect them there. - **The agent never holds the token.** It is kept by the daemon and never injected into the agent's environment, which is what makes the card an approval rather than a formality. ## A sandbox as a file `--definition` takes a [sandbox.toml](https://intentic.dev/docs/sandbox-definitions/), the same document the Environment tab exports: the workspace repo, the repositories to clone, the capabilities the box should have, the secret names to fill in, the overlay Dockerfile and the settings that differ from their defaults. The new sandbox applies it on first boot, on a workspace that arrived empty. That is what turns a team of specialized agents into something you can review. The roles live in your repository as files; bringing one up is a command, and what it will be is a diff somebody read. ## Another sandbox, or another persona? Go by what is actually different. A sandbox is a machine: its own environment, its own connected services, its own workspace and its own blast radius. If the only difference is how a turn behaves — which model, which folder, which tone, which of the tools already here — that is a [persona](https://intentic.dev/docs/worksite/#ws-persona), and personas are free. A sandbox is a container one of your computers has to run. ## Related pages - [Autonomous employees](https://intentic.dev/docs/autonomous-employees/): what to put in a sandbox once it exists, and how a team of them hands work down the line. - [Sandbox definitions](https://intentic.dev/docs/sandbox-definitions/): the TOML a new sandbox seeds itself from, and what it deliberately cannot carry. - [Your own machine](https://intentic.dev/docs/your-machine/): connecting the computer a new sandbox is built on, and the switch that permits it. - [Remote runners](https://intentic.dev/docs/remote-runners/): the other answer to 'not on this box': moving a turn's compute without giving the work its own machine. More in Agent Orchestration [Previous ← Remote runners](https://intentic.dev/docs/remote-runners/)[Next Automations, workflows & loops →](https://intentic.dev/docs/automations/)