Skip to main content

Pi Sandbox

Cosmonic Desktop is a local AI sandbox for Pi: the code Pi writes is compiled to WebAssembly and runs on your own machine with no access to your files, network, or keys until you grant it. Two settings wire it up, one for launching Pi from Builder with the sandbox playbook and one for installing Desktop's MCP server into Pi; use either or both.

Sandbox Pi with Cosmonic Desktop​

1. Settings → Agents: launch Pi from Builder​

Open Settings → Agents. The Detected agents card lists every coding agent Desktop found by its home directory (~/.pi) or on your login shell's PATH, and says whether each one is launchable from Builder. In the Skills card, turn on Pi to install the cosmonic-sandbox skill at ~/.pi/agent/skills/cosmonic-sandbox/. This is the same install the one-time Set up your coding agents dialog offers on first run; nothing is installed silently.

The skill is the sandbox playbook: it teaches Pi to compile what it generates to a WebAssembly component and deploy it into the local sandbox instead of running it raw on your host. Once it is installed, Builder can launch Pi directly: open Builder, pick Pi as the agent, describe what you want, and its output lands in a sandboxed workload you can inspect before it runs.

Desktop installs the skill into Pi's own agent directory rather than the shared ~/.agents/skills alias, because Pi's own directory takes precedence and this is what makes it load the Pi build of the skill.

2. Settings → MCP Server: install Desktop's MCP server into Pi​

Pi ships no MCP client of its own, so there are two parts. First install the pi-mcp-adapter package once; it adds an MCP client to Pi and reads the standard mcpServers schema from ~/.pi/agent/mcp.json:

pi install npm:pi-mcp-adapter

Then open Settings → MCP Server and turn on Pi under Install in your AI client: Desktop writes the entry to ~/.pi/agent/mcp.json (Pi's own file, never the shared roots the adapter also reads). The manual equivalent (using the daemon binary's path on your platform—macOS shown):

{
  "mcpServers": {
    "cosmonic": {
      "command": "/Applications/Cosmonic Desktop.app/Contents/Resources/cosmonicd",
      "args": ["mcp", "serve"]
    }
  }
}

3. Verify the connection​

Start pi and ask it to list Cosmonic workloads; with the adapter installed the cosmonic_* tools answer while Desktop is running. Builder launches Pi in "Sandbox only" mode by default (--exclude-tools bash), so the agent can build and deploy into the sandbox but cannot run shell commands on your host.

Skills over MCP​

Desktop's MCP server also publishes its skill family—cosmonic-sandbox, cosmonic-go, cosmonic-nats, cosmonic-nats-tuning, and cosmonic-kafka—through the MCP Skills extension (io.modelcontextprotocol/skills). A client that supports Skills over MCP gets the playbooks the moment it connects, with nothing written to its skills directory, so the MCP registration above is enough on its own for those clients. The on-disk skill from Settings → Agents covers clients that read a skills directory but do not yet speak the extension, and it is what Builder relies on to launch Pi.

What Pi can do once connected​

Its full tool surface (observe, deploy, build) and the guardrails are covered in Connect Coding Agents; the tools work only while Cosmonic Desktop is running.

Frequently asked questions​

How do I sandbox Pi?

Install Cosmonic Desktop, then under Settings → Agents turn on Pi to install the cosmonic-sandbox skill, and under Settings → MCP Server register Desktop’s MCP server in Pi. From then on the code Pi writes is compiled to WebAssembly and runs in a local sandbox with no access to your files, network, or keys until you grant it.

Does Pi itself run inside the sandbox?

No. Pi keeps running in your terminal or IDE exactly as before. What changes is where its output executes: the programs and MCP servers it builds run as sandboxed WebAssembly workloads on your machine instead of directly on your host.

Do I need both the skill and the MCP server?

They do different jobs. The MCP server gives Pi the tools to build, deploy, and observe sandboxed workloads; the skill gives it the know-how to use them by default. Desktop also publishes its skills over the MCP Skills extension, so a client that supports Skills over MCP gets the playbook from the connection alone.

What can the code Pi writes reach inside the sandbox?

Nothing by default. Each workload starts with no filesystem, network, or credential access; you grant exactly the capabilities it needs in its manifest, and everything else stays denied. The same manifest deploys unchanged to Cosmonic Control on Kubernetes.

Why does Pi need pi-mcp-adapter?

Pi has no built-in MCP client; its philosophy is CLI tools with READMEs. The pi-mcp-adapter package adds one and reads the standard mcpServers schema from ~/.pi/agent/mcp.json, which is the file Desktop writes. Without the adapter the Cosmonic tools never load.

Next steps​

Last updated on by Liam Randall