Sandboxing
Every agent turn runs inside four boxes nested one in another: a machine, a sandbox on it, the area of the person who started the conversation, and the agent's own checkout. Each box is cut from the one around it and can never be wider.
On this page(10 sections)
- The four boxes
- 1. A machine runs your sandboxes
- 2. A sandbox is one project's space
- 3. Each person holds an area
- 4. An agent works with its person's access
- Walls and lanes
- The sandbox is the wall. An area is a lane.
- The sandbox's own configuration is never in an area
- Maintainers and the owner are not fenced
- An area, a sandbox, or a persona
The four boxes
| Box | Holds | Its edge is kept by |
|---|---|---|
| Machine | Your device or ours · Docker · Several sandboxes | Docker: separate containers, separate volumes |
| Sandbox | Repositories on /work · Tools, skills, extensions · Accounts and personas | the container, and the daemon inside it |
| Area | Named folders · Personas homed there · A tier: what they may do | the daemon, on every request |
| Agent | Its starter's areas · Narrowed by its persona · Its own branch | a per-turn sandbox: its own user, its own processes, only its folders on disk |
1. A machine runs your sandboxes
Your laptop, a server you rent, or a machine we host. It runs Docker and provides processors, memory and disk. One machine runs several sandboxes side by side, and they share nothing: each has its own container and its own volumes.
The machine decides how fast work runs and nothing else about it. Moving a sandbox to a bigger machine keeps its address, its files and its history. A sandbox runs unprivileged by default. Anything that needs more of the machine, such as its own Docker engine or a GPU, is a capability the owner turns on. See where it runs for the choice of machine.
2. A sandbox is one project's space
One container where people and agents work on the same problem in the same environment. Its image decides which tools exist, so every turn finds the same ones. The sandbox grows its own environment: an agent proposes a tool, the owner approves it, and it becomes part of the image. Repositories live on /work and the record on /history, so both survive updates.
A sandbox is meant to last. It holds many conversations at once, keeps working after you close the browser, and builds up the way its project is done: the accounts and services it is connected to, theextensions installed in it, its skills, and its personas. When an agent needs a tool the image lacks, it proposes the change and the owner approves it, so the next turn and the next person find the same tools. The shape of all this exports as a sandbox definition, which can rebuild the same environment elsewhere.
Nothing crosses between two sandboxes. They are separate containers with separate volumes, even when they run on the same machine.
3. Each person holds an area
An area is a named set of folders. Access gives each person a tier and the areas they hold; holding no area means the whole workspace. The daemon checks every file listing, read, write and search a person makes against it. The personas a person may pick are the ones homed inside their area, each with its own accounts and powers; a guest talks only through those.
Areas are defined once under Sandbox → Areas, as a name and a list of folders, and handed out per person under Sandbox → Access. Naming them rather than listing folders on every person means that a new folder is one edit, and two people meant to see the same thing can't drift apart. The definition is a tracked file, so a change to who sees what shows up in review like any other change. Editing an area moves everyone who holds it at once, including conversations already running.
How areas combine with tiers:
- A writer needs at least one area: it is where they may change files. They can't land or publish.
- A guest needs at least one area too: the personas homed in it are the ones a guest talks through.
- A viewer or collaborator may be given areas to narrow what they see, or none for the whole workspace.
- A maintainer can't be given areas. See below for why.
4. An agent works with its person's access
A conversation takes the areas of whoever started it and keeps them from its first turn. A persona can narrow that further, never widen it. Each turn then runs in a box of its own inside the sandbox: an unprivileged user, its own processes, and a filesystem built from the folders it holds and the tools it needs, with no git history. The daemon commits its work to the conversation's own branch, where it waits until someone allowed to land it does.
Agents don't have access of their own. A conversation started by a person in the support area works in support, whoever later reads it, and keeps that fence for its whole life even if the person's grant changes. A persona homed in a narrower folder narrows the turn further. Its edits go to the conversation's own branch, so nothing reaches the main tree until someone allowed to land it reviews the diff. For the branch mechanics, see parallel agents.
Walls and lanes
Nested boxes look like walls all the way down. They aren't, and it matters which edges you lean on.
The sandbox is the wall. An area is a lane.
Two sandboxes are separate containers with separate files, and nothing in one can reach the other. Areas divide one sandbox between people who work together. A person's requests are refused outside their area, and their agent's turn runs with nothing else of the tree on disk, so even a command the agent writes itself finds nothing of the rest there. What an area doesn't split yet is the network: a fenced turn shares the sandbox's, including services other conversations run on it, such as a dev server or a database. If someone must never see the rest of a workspace, give them a sandbox of their own that holds only what they may see.
The sandbox's own configuration is never in an area
No area can include the sandbox's settings or its public outbox. So a grant below maintainer can never reach the files that decide what agents may do, who is invited, or what gets published.
Maintainers and the owner are not fenced
A maintainer holds the owner's operating authority: they read every credential and can drive every conversation. A folder fence on that tier would only be a line on a screen, so the daemon refuses to set one.
An area, a sandbox, or a persona
| You have | Use | Why |
|---|---|---|
| Teammates who should each stay on their own part of one project | Areas | One environment, one set of tools, and work that lands in one tree. Each person and their agents see only their part. |
| A customer or contractor who must never see the rest of the code | Another sandbox | Its own container and volumes, holding a clone of only what they may see. Nothing of yours is in the box to reach. |
| Two unrelated projects, or two jobs whose credentials must not meet | Another sandbox | Separate tools, accounts, secrets and history. One machine can run both. |
| The same people, but a task that needs other accounts or fewer powers | Another persona | Same sandbox and area, with a different set of accounts and powers handed to the turn. |
Related pages
- Access & sharing: the tiers, and how an invite carries areas.
- The worksite: machine, sandbox, persona and project as one picture.
- Architecture: where identity, code, state and compute live.
- Docker setup: the container, its volumes and its capability posture.