Pi
The CreateOS extension for the Pi coding agent does two things: it adds a full set of sandbox tools to any Pi session, and — when you ask for it — it redirects Pi's own built-in tools so that reading, writing, and running commands all happen inside a remote sandbox instead of on your machine.
At a glance
- Package:
@createos/pi - Activation:
--inside-createos-sandbox - Tools: 41 — 7 built-in replacements plus 34 sandbox tools
- Commands:
/sandbox,/network,/device - Auth:
createos login
Prerequisites
Install the createos CLI:
Bash
Then authenticate. At a terminal, sign in:
Bash
For CI or headless use, set an API key instead:
Bash
The extension holds no credentials of its own — it shells out to the CLI and uses whatever session the CLI has.
Install
Bash
Install from the repository root — the root manifest is what exposes the extension to Pi.
Two ways to use it
Tools only. Start Pi normally. The 34 sandbox_* tools are available, so the agent can create boxes, run commands on them, and manage networks and disks — but Pi's own bash, read, and write still act on your machine.
Everything remote. Add the activation flag:
Bash
Now a sandbox is created when the session starts, and Pi's built-in bash, read, write, edit, ls, find, and grep all operate inside it. The working directory is /root/workspace.
The --createos-* flags below only take effect alongside --inside-createos-sandbox. On their own they are silently ignored.
Flags
| Flag | Purpose |
|---|---|
--inside-createos-sandbox | Run Pi's built-in tools inside a sandbox |
--createos-shape <shape> | Machine size (default s-2vcpu-2gb) |
--createos-rootfs <name> | Base image or template |
--createos-network <names> | Private networks to join, comma-separated |
--createos-sync-once | Copy the project to /root/workspace before Pi starts |
--createos-watch | Keep the project and /root/workspace in sync all session |
--createos-avoid-git-ignore | Include gitignored files in --createos-sync-once |
--createos-sync-once and --createos-watch cannot be combined.
Getting your project into the box
A fresh sandbox is empty. Two flags fill it, and they behave differently.
--createos-sync-once copies the project in once, before the agent starts. It archives your directory and unpacks it at /root/workspace. Version control directories are always skipped, and gitignored files are skipped too unless you pass --createos-avoid-git-ignore. Because it only ever adds, files that exist only in the sandbox survive.
--createos-watch starts a continuous two-way sync instead, so edits on either side propagate for the whole session. It carries no default exclusions — everything in the directory is in scope.
For safety, neither will sync your home directory itself, the filesystem root, or sensitive directories such as .ssh, .aws, .gnupg, .kube, and .docker.
Tools
Seven tools replace Pi's built-ins and keep their original names — bash, read, write, edit, ls, find, grep. They route to the sandbox when one is active and behave normally otherwise.
The remaining 34 are new capability:
| Group | Tools |
|---|---|
| Lifecycle (8) | sandbox_create, sandbox_exec, sandbox_info, sandbox_list, sandbox_pause, sandbox_resume, sandbox_fork, sandbox_destroy |
| Configuration (5) | sandbox_ingress, sandbox_firewall, sandbox_bandwidth, sandbox_shapes, sandbox_images |
| Ports and sync (3) | sandbox_preview_url, sandbox_tunnel, sandbox_sync |
| Networks (6) | sandbox_network_create, sandbox_network_list, sandbox_network_show, sandbox_network_attach, sandbox_network_detach, sandbox_network_delete |
| Disks (6) | sandbox_disk_create, sandbox_disk_list, sandbox_disk_show, sandbox_disk_delete, sandbox_disk_attach, sandbox_disk_detach |
| Device VPN (5) | sandbox_device_register, sandbox_device_status, sandbox_vpn_up, sandbox_device_attach, sandbox_device_detach |
| Fan-out (1) | sandbox_fanout |
Most tools take an optional sandbox ID and fall back to the active sandbox. sandbox_resume and sandbox_destroy are the exceptions: both require an explicit ID, because resuming or deleting the wrong box is not something to infer.
sandbox_vpn_up is advisory. Bringing up a WireGuard tunnel needs sudo, so the tool returns the command for you to run yourself rather than running it.
Fan-out
sandbox_fanout runs several scenarios at once, each in its own sandbox, up to three in parallel. Each scenario gets a copy of the project and runs its command in /root/workspace.
A scenario that names a port is treated as a service: it starts under tmux, gets a public HTTPS URL, and is health-checked — up to 15 attempts, one second apart, optionally requiring a string in the response body. Scenarios without a port simply run to completion. Either way the sandbox is destroyed when the scenario ends, including on failure.
Commands
| Command | What it does |
|---|---|
/sandbox | Show the active sandbox — ID, status, working directory, public URL |
/network create | ls | show | rm | attach | detach | Manage private networks |
/device status | attach | detach | Manage device VPN access |
/network also accepts list and delete as aliases for ls and rm. /device defaults to status when given no arguments.
Session lifecycle
The sandbox is created at session start and /root/workspace is created inside it.
What happens when you quit depends on whether the session was saved. A persisted session leaves the sandbox running and prints its ID, so that resuming the session reattaches to the same box — and if it had been paused meanwhile, resuming the session resumes the box too. An ephemeral session destroys the sandbox on exit.
That distinction matters for billing: a persisted session's box keeps running until you pause or destroy it. The exit message includes the createos sandbox rm command for exactly that reason.
Starting a new session, resuming one, or forking one all leave any existing sandbox untouched.
See also
- OpenCode — the same tool surface for a different agent
- CLI reference — what the tools call underneath
- Concepts — sandboxes, networks, ingress, snapshots