Skip to main content

Pi Agent Sandbox

A Pi agent sandbox runs Pi where it cannot reach your files, your network or your API keys. Cosmonic Desktop does this on its Agents page: Pi's agent loop (pi-agent-core) is compiled to a WebAssembly component that imports no network and no filesystem, so Desktop makes every model call and runs only the tools you grant. The same image, ghcr.io/cosmonic/agents/pi, deploys to Kubernetes with Cosmonic Control.

Why sandbox Pi​

Pi is deliberately small: a minimal core, a handful of tools including bash, and packages you add with pi install. It does not stop to ask before it runs a command. That is what makes it fast to work with, and it also means every command Pi runs, and every package you add, runs with your user's permissions: your home directory, your SSH keys, your cloud credentials and your network.

A sandbox moves that boundary. Pi can reach only what you grant, and the grant is checked by the host, not by the agent.

Run Pi in a sandbox in Cosmonic Desktop​

1. Start a Pi session​

  1. In Desktop, select Agents under AI & agents in the sidebar. If you already have sessions, select New.
  2. Select the agent chip next to the message box and choose Pi.
  3. Select the Model chip. Choose a source (such as Ollama on this machine, or Add a source… to enter an API key), choose a model, then select Done. Desktop keeps the key; Pi asks the host for a model by its alias and never sees it. See Choose the model.

2. Give Pi a folder​

Pi has no files of its own. To let it work on a project, choose one folder:

  1. Select the folder chip under the message box, which shows No folder, then Choose a folder…, and pick the folder.
  2. Select the access chip next to it and choose Read only, Edit with undo or Ask before each edit.

Desktop adds the folder tools that match: Workspace (read) always, git when the folder is a git repository, and Workspace (write) unless you chose Read only. Each one sees that folder and nothing outside it.

3. Add tools and start​

  1. To give Pi more than the folder tools, select Tool settings…, then Add tools yourself…, find a tool in Search tools, and select Add. Each tool's card says what it reaches, such as one host.
  2. To approve each host the first time a tool reaches it, turn on Ask first before a tool reaches each host.
  3. Select Done, type your first message, and start the session.

Pi streams its reply as the model writes it. Close the session and open it again later: Desktop keeps the conversation, not Pi.

4. Check what Pi can reach​

Select Show session details in the session header. This session can… lists each kind of reach (Change files in a folder, Read a folder, Reach hosts) with the tool that grants it. Select a tool to see every call Pi made through it.

The full set of tool and host options is in Give an agent a tool.

Run Pi on Kubernetes with Cosmonic Control​

The Pi image exports cosmonic:agent/run, so Control drives it the same way as any other agent harness. Follow Run an agent on Control and use the Pi image for the agent component:

components:
  - name: agent
    image: ghcr.io/cosmonic/agents/pi@sha256:78d319296cffe646f82f299b77c6890e494f36157774401a429ea0349684c467 # 0.41.0, the release Desktop runs
    localResources:
      allowedHosts: []

The agent keeps allowedHosts: []. Tools are their own components in the same workload, each with its own hosts or volume; see Give an agent a tool. Runs start over HTTP with the OpenAI Responses API or over NATS, and the workload spec goes through the same RBAC and admission policy as your other manifests.

What sandboxed Pi can reach​

The Pi component imports these interfaces from cosmonic:agent, and nothing else that reaches outside it:

  • cosmonic:agent/models and cosmonic:agent/chat: a model, by an alias the host resolves. The host makes the call with credentials Pi never holds.
  • cosmonic:agent/tools: the tools the session or workload grants.
  • cosmonic:agent/session: the conversation and a journal of every step and tool call, kept by the host.

It also uses a clock and random numbers.

Outgoing HTTP, sockets and the filesystem are absent from the compiled component, not blocked by a policy. Desktop reads an agent's imports before it runs it and refuses one that imports the network or the filesystem.

What changes from the pi CLI​

  • The loop is Pi's. It is pi-agent-core, running on a small JavaScript engine inside the component, with context compaction when the conversation reaches 90 percent of the model's window.
  • No built-in shell or file tools. Pi's own tools, such as bash, read and edit, are not in the component. The folder tools and catalog tools Desktop grants take their place, each with its own reach.
  • Packages and extensions come from the catalog. Packages you add with pi install do not load in the sandboxed agent. Add the tools you want to Desktop's catalog in Settings → Tools instead; a tool can be an image, a component file, or a remote MCP server.
  • The host keeps the conversation. The component holds nothing between turns, so a session survives restarts and a run on Control can be served by another replica.

Pi sandbox or a container?​

Running pi in Docker or a devcontainer puts one wall around the whole process. Pi, its bash, its packages and your API key share the box, and anything Pi runs can read that key and reach whatever the container's network allows.

The Cosmonic sandbox splits those parts. Pi's loop has no network and no key. Each tool has its own grant: one folder, or a short list of hosts. A package that misbehaves can reach only what its own grant allows, and the record of what it called is in the session.

Frequently asked questions​

How do I sandbox the Pi coding agent?

Install Cosmonic Desktop, open Agents, select New, and choose Pi in the agent chip. Pi’s agent loop then runs as a WebAssembly component with no network, files or API keys of its own, and reaches only the folder and tools you grant.

Does Pi itself run inside the sandbox?

On Desktop’s Agents page and on Cosmonic Control, yes: Pi’s agent loop is the sandboxed component, and the host makes every model call and tool call for it.

Can sandboxed Pi run shell commands?

No. The sandboxed Pi has no bash tool and no import that could start a process, open a connection or read a file. It works through the tools you grant, such as Workspace (read), Workspace (write) and git for one folder.

Where are my API keys when Pi runs in the sandbox?

With the host. Pi asks Desktop or Control for a model by an alias such as default, and the host makes the call with a key Pi never sees. On Desktop the key stays in your system keychain or the secret store you chose; on Control it is a Kubernetes secret.

Do Pi packages and extensions work in the sandbox?

Packages installed with pi install do not load in the sandboxed agent. Add the tools you need to Desktop’s tool catalog instead, as an image, a component file or a remote MCP server. Each tool runs as its own component with its own grant.

Can I run the same Pi agent on Kubernetes?

Yes. Deploy the ghcr.io/cosmonic/agents/pi image as the agent component of a Cosmonic Control workload. It keeps no network of its own, and its tools are separate components with their own grants in the same manifest.

Next steps​

Last updated on by Eric Gregory