cherry π is a workspace for the terminal programs you already use and the agents you work with. It runs on your machine. It connects to another machine only when you pair them, and you decide what each person and each agent may touch.

One layer per project

Open cherry π in your terminal, Ghostty for example. Each project gets a layer: its folder, its panes and its conversation with Picache, cherry π's own agent. Split a pane to run the tests next to the code, keep Neovim or lazygit in another, and switch layers when you move to the next project. The layer you left keeps running.

If you know tmux or Zellij, panes and layouts will feel familiar. You can arrange them with the mouse, from a shell with the picache command, or from a Lua script.

Your work stays on your machine

Conversations and run records are kept in SQLite files in your workspace. Terminal processes run apart from the desktop client, so quitting the client leaves your terminals running, and opening it again reconnects to them.

What runs where Desktops, this window, another window on the same workspace, or a paired machine's desktop over P2P, connect to one harness per workspace through run/harness.sock. The harness, cherrypi.ape, holds policy, grants and budgets, runs turns and Picache, keeps the stores, receipts and chains, runs jobs, Conduit and the P2P core, and is the one door for capsules. Each terminal is held by a pump of its own; a program in a pane reaches the harness through picache.sock with its pane's token. Sidecars: the signer holds the keys, the P2P sidecar runs on Bare in a box of its own, and llama-server runs as a job. Capsules, app handlers, scripts, clean rooms and Run one, start through the one door. A desktop quitting leaves the harness and pumps running; a new build replaces the harness and the pumps stay; a reboot ends everything. DESKTOPS this window the Go desktop another window the same workspace a paired machine in a pane here, over P2P THE HARNESS · cherrypi.ape one per workspace policy, grants, budgets turns, and Picache stores, receipts, chains jobs, Conduit, P2P core the one door for capsules ◂ run/harness.sock ◂ picache.sock PUMPS · ONE PER TERMINAL zsh run/tty/<id>, its ring claude, in its box picache, its own token SIDECARS signer · holds the keys P2P · Bare, boxed llama-server · a job CAPSULES · THROUGH THE ONE DOOR app handlers · scripts · clean rooms · Run one WHAT OUTLIVES WHAT a desktop quits: harness and pumps run on a new build: harness replaced, pumps stay a reboot: everything ends
What runs where, and what outlives what.

A layer can leave as one signed file holding its history and its folder, and be imported on another machine. Its permissions stay behind, and the receiving workspace grants its own. Tools you build travel the same way: a .pi app is a single SQLite file with its code, its assets and its data.

Harnesses compose

An agent harness runs a model and its tools in a loop until a task is done. Claude Code and Codex are harnesses of that kind, and Picache has one of its own. cherry π is the harness around them: the workspace that holds the projects, decides what each agent may reach, and keeps a record that outlasts any single turn.

Each layer controls its own part. A vendor agent keeps its own loop and tools inside cherry π. cherry π can run it in a box that limits which files and network it reaches, and it checks and records the calls the agent makes through cherry π. It does not see or approve every step inside the vendor's loop.

Box the agent, not its commands Left: an agent's own sandbox boxes only its shell commands; the agent, its hooks, MCP servers and login stay outside, so a hook can read ~/.ssh. Right: cherry π boxes the whole agent with its hooks and MCP servers; only its folder, its config and its own temp folder are writable, and the same hook stops at the box wall. AN AGENT'S OWN SANDBOX the agent its hooks its MCP servers its login shell commands the only thing boxed ~/.ssh a hook reads ~/.ssh CHERRY Π THE BOX the agent its hooks · MCP servers its login token its folder · its config ~/.ssh your home cherry π state ✕ the same hook stops at the wall their sandbox holds the commands cherry π holds the agent
The agent's own sandbox is drawn dashed, and cherry π's box solid.

Give an agent a goal and keep the decision

A goal gives an agent its own copy of the project. The agent changes the copy, the project's tests run after each step, and Picache reviews the result. Your project is untouched until you accept the work. If you reject it, the branch is kept for the record.

A goal, from copy to merge You give a vendor agent a goal with picache goal. It works in its own copy of the layer, .worktrees/goal-id, on a branch cherrypi/goal-id, and writes there and nowhere else. Each step is its turn, then the layer's tests; a test failure becomes the next step's work, and every step is committed to the branch. When the tests pass or the steps run out, Picache reviews the branch, reading only. Then you decide: accept merges it into the layer, reject keeps the branch for the record. The layer is untouched until you accept, and a conflict refuses the merge whole. Without git, the copy is the whole folder, snapshots stand in for commits, and the merge is three-way, with an undo. YOU picache goal @claude "…" only you give one ITS COPY OF THE LAYER .worktrees/goal-<id> branch cherrypi/goal-<id> a step: its turn then the layer's tests ✕ tests fail: next step every step: a commit it writes here, nowhere else PICACHE reviews it it only reads: what it did, what looks wrong, accept or not ✓ tests pass, or steps run out YOU DECIDE ✓ accept merged into the layer ✕ reject the branch kept for the record either: copy gone THE LAYER IS UNTOUCHED UNTIL YOU ACCEPT · A CONFLICT REFUSES THE MERGE WHOLE without git: a copy of the whole folder, a snapshot per step, and a three-way merge with an undo
A goal: worked in a copy, reviewed by Picache, decided by you.

If something is cut off halfway, such as a write whose outcome is unknown, Recovery holds it for you to settle before anything continues.

Machines meet as peers

Every installation has its own identity. Two machines find each other with a shared secret, and pairing needs the other operator to say yes. Pairing grants nothing by itself. Each share is for one workspace, one layer or one terminal, and you can take it back.

Finding a machine, then pairing with it Finding: picache fleet new makes a secret, and fleet join adds each other machine. Fleet machines announce on a rednet topic hashed from the secret, and on one local network also send an mDNS beacon that hashes only the fleet tag. The open directory is off unless you turn it on. Pairing: the laptop runs picache pair studio and sends a signed invite that spends a one-time nonce. Studio holds it as a request for ten minutes, and its operator approves it with pair approve. Studio answers with its acceptance and a contract offer, and the laptop sends its own contract back. Each side pins the other's key, and each direction has a contract of six exact scopes, for 30 days, renewed while the machines stay paired. A beacon is a hint, never trust: nothing admits an unpaired machine. FINDING picache fleet new then fleet join <secret> on each rednet: a topic hashed from the secret LAN: an mDNS beacon only its fleet tag hashed open directory: off laptop asks studio approves a signed invite, one-time nonce ? pair approve within 10 minutes accepted, with its contract its contract back KEYS PINNED · A CONTRACT EACH WAY · 6 EXACT SCOPES · 30 DAYS, RENEWED a beacon is a hint, never trust: nothing admits an unpaired machine unpairing revokes what this machine issued
Finding a machine takes a shared secret, and pairing with it takes the other operator's yes.

Layers on one machine, linked workspaces and paired machines all send offers and replies the same way, through an outbox, an inbox and receipts, so a request is still tracked after the connection that carried it has gone. Connections may pass through relays. The work, and the decisions about who may use it, stay with the people running the machines.

Try it

cherry π is an engineering prototype. The local workspace, layer exports, pairing and scoped shares work. Live layers between two physical machines are still being tried. The manual says what works today and what doesn't yet. Join early access to get a build and tell us where it breaks.