You ask an agent to inspect a repository. It needs the project files and its own tools. It does not need your SSH keys, Cherry Pi's state or an open route to every host on the network. Cherry Pi puts the process in a capsule: a confined place to run, with its reach decided before it starts.

The same mechanism serves more than agents. A Lua script written by Picache, an app handler, a command examining an unfamiliar archive and a task hosted on a paired machine all start through one door. Their jobs differ, so their capsules do too. The door builds each boundary from a named profile and refuses the run if the machine cannot enforce it.

One door, or nothing Agents, scripts, app handlers, clean rooms and capsules from paired machines all pass through one door. On a machine that can confine they run confined, by Seatbelt on macOS or bubblewrap or Landlock on Linux. On a machine that cannot, they are refused with the reason. A capsule has no unconfined path. The signer and the P2P sidecar are not capsules and start outside the door; the sidecar has a box of its own. an agent a script an app's handler a clean room a paired machine's capsule ONE DOOR A MACHINE THAT CAN CONFINE Seatbelt on macOS bubblewrap or Landlock on Linux ✓ runs confined; its record says how A MACHINE THAT CANNOT ✕ refused, with the reason a capsule has no unconfined path
Everything that runs confined starts through one door.

What the boundary covers

A capsule has two kinds of reach. The operating system limits what its process can touch directly: files, processes and network connections. The broker seal limits what that process may ask Cherry Pi to do on its behalf. Both come from the same profile at launch. Passing the broker seal still does not grant an action; the workspace applies its normal permission checks to that request.

Take a script that Picache writes to arrange a test run. The script runs in a capsule, with a call budget and a sealed set of workspace verbs drawn from the calling turn. If that turn could only read, the script cannot acquire a write verb by calling it from Lua. If the verb is available, its call still goes through the same policy and receipt path as a direct picache command. The Lua article explains when to use picache script and when to use an operator-authored picache do script.

For a vendor agent, the whole CLI runs in the box, including hooks and tools it starts. Its pane's project folder is writable; the rest of the home folder and Cherry Pi's state are outside its reach. The agent's own harness still decides how to respond to your prompt. Cherry Pi governs the workspace operations it receives and confines the process's direct reach. It does not claim to review every internal step in a vendor agent.

A room for unknown input

Suppose someone sends you an archive. You want a list of its contents, or perhaps a converted document, without letting the tool you use wander through your machine. A clean room copies the input from your current folder into a private ground. It runs with no network and no broker verbs. Your original file stays where it was.

picache cleanroom invoice.zip -- unzip invoice.zip -d out/

Only regular files written under out/ are kept in Cherry Pi's state after the process ends. The reply gives you the exit result, the end of the log and the exported files. The rest of the ground is removed. The default lifetime is five minutes, with an hour as the ceiling. You can also run a Lua script this way, or opt into read-only access to installed tools with --tools.

A clean room, from copy to out/ picache cleanroom copies its inputs, which must be inside your folder, into a capsule's ground: a folder of its own. The command runs there with no network and nothing to ask the harness, under Seatbelt on macOS, or bubblewrap or Landlock on Linux. It lives five minutes by default and an hour at most. When it ends, out/ is kept in cherry π's state and listed in the reply, with the end of its log and its exit; the capsules chain records its start and end; everything else is deleted. Your originals are never touched. With no way to confine here, the run is refused, never run unconfined. YOUR FOLDER invoice.zip inputs from inside your folder only ✓ never touched THE CAPSULE · ITS GROUND a copy of invoice.zip unzip invoice.zip -d out/ ✕ no network, nothing to ask Seatbelt, bubblewrap or Landlock 5 min by default, 1 h at most WHAT COMES BACK out/ kept in cherry π's state its log's end, its exit a start and an end on the capsules chain ✕ the rest is deleted NO WAY TO CONFINE HERE: THE RUN IS REFUSED, NEVER UNCONFINED a script runs the same way: picache cleanroom data.csv --lua summarize.lua
A clean room takes copies in and gives out/ back. Nothing else passes in either direction.

The machine matters

On macOS, the capsule door uses Seatbelt. On Linux it uses bubblewrap where bubblewrap can actually start, and Landlock otherwise. The record names the mechanism that held the process. If no available mechanism can provide the requested profile, the run is refused with a reason. A paired machine can host a capsule when the operator has enabled that role; its own door must be able to confine the run.

These mechanisms do not provide identical boundaries. Landlock can prevent a capsule from reading a private path while still allowing it to learn that the path exists. Seatbelt has no syscall filter. An agent can also be launched standard if the operator changes that agent's setting; the run is then labelled as standard, not represented as a capsule. Cherry Pi records what it used rather than calling all of these runs equally isolated.

A capsule shares its host's kernel. It reduces what a process can reach, but it is not a virtual machine for hostile binaries. The confinement manual covers the exact profiles, agent settings, platform behaviour and commands.