Pi coding agent sandbox: run Pi's tools in a CreateOS microVM

Pi coding agent sandbox: run Pi's tools in a CreateOS microVM

To give the Pi coding agent a sandbox off your machine, install the CreateOS extension for Pi, sign in with createos login, and start Pi with pi --inside-sandbox. Pi keeps running on your machine. Its built-in tools for reading, writing and running commands act inside a remote sandbox instead.

This guide is about Pi, the terminal coding agent from pi.dev that you start with the pi command. Its own README describes it as "a minimal, extensible agent harness that you can make your own." CreateOS Sandbox runs each sandbox as a Firecracker microVM with its own guest kernel, root filesystem and network identity.

The extension is maintained by CreateOS and is not a product of Pi's authors.

Key takeaways

• pi --inside-sandbox creates a sandbox at session start and routes Pi's seven built-in tools into it.
• The sandbox starts empty. Add --sandbox-sync-once to copy your project to /root/workspace first.
• An ephemeral session destroys its sandbox on exit. A saved session leaves it running until you pause or destroy it.
• Outbound network access is open until you set a rule. The sandbox_firewall tool sets one.

What does the CreateOS extension add to Pi?

The extension adds sandbox tools to every Pi session and, with one flag, moves Pi's own tools into a sandbox. The Pi docs page describes two ways to use it:

• Tools only. Start Pi normally with pi. The agent gets sandbox_* tools to create boxes, run commands on them, and manage networks and disks. Pi's own bash, read and write still act on your machine.
• Everything remote. Start Pi with pi --inside-sandbox. A sandbox is created at session start, and Pi's seven built-in tools run inside it. The working directory is /root/workspace.

The extension holds no credentials of its own and uses the createos CLI's session. For background, read what an AI agent sandbox is.

How do I set up a Pi coding agent sandbox?

Three steps take you from install to a Pi session whose tools run remotely. You need Pi, a CreateOS account and a project directory.

Step 1: How do I install the CreateOS extension for Pi?

Install it with Pi's own package command from the repository root. Copy the exact command from the Install section of our docs. The root manifest is what exposes the extension to Pi.

The extension installs the createos CLI at session start if it is missing. Set COS_NO_AUTOINSTALL=1 to turn that off, or follow the Prerequisites section to install it yourself.

Step 2: How do I sign in to CreateOS for Pi?

Run createos login at a terminal. For CI or headless use, set an API key instead:

export CREATEOS_API_KEY=<key>

If tmux is installed and you are signed out, the extension starts the browser sign-in for you.

Step 3: How do I start Pi inside a sandbox?

Add --inside-sandbox when you launch Pi, plus --sandbox-sync-once to bring your project with you.

pi --inside-sandbox --sandbox-sync-once

--sandbox-sync-once copies your directory to /root/workspace before the agent starts. Run /sandbox inside Pi to see the active sandbox's ID, status, working directory and public URL.

Older instructions use --inside-createos-sandbox and --createos-* flags. Those names were retired. The old activation flag now reports an error, blocks host tools and starts no sandbox.

Which flags control the Pi sandbox?

Six --sandbox-* flags shape the box, and they only work alongside --inside-sandbox. Per the extension README:

--sandbox-sync-once and --sandbox-watch cannot be combined. The one-time copy skips version control metadata and Git-ignored files, and it keeps files that exist only in the sandbox. --sandbox-watch runs a two-way sync that skips version control directories but not Git-ignored files. Neither will sync your home directory, the filesystem root, or folders such as .ssh, .aws, .gnupg, .kube and .docker.

Is the Pi sandbox open to the internet?

Yes. Outbound traffic is open until you set a rule, and the session's sandbox is created with its public HTTPS URL switched on. With no egress rules a CreateOS sandbox can reach any host. Once any rule is set, only listed destinations pass and everything else is dropped in-kernel on the host, outside the VM (Limits and defaults).

pi --inside-sandbox sets no egress rules. Ask Pi to call sandbox_firewall with the hosts your work needs, such as pypi.org. Rules accept hostnames, *. wildcards, IPs and CIDR blocks, as listed in the Egress rule formats. The sandbox_ingress tool turns the public URL off.

For why a separate kernel matters here, read why microVM isolation matters for agents.

What happens to the sandbox when I quit Pi?

It depends on whether the session was saved. Per the Session lifecycle section:

• Ephemeral session. The sandbox is destroyed on exit.
• Saved session. The sandbox keeps running and Pi prints its ID with a createos sandbox rm command. Resuming the session reattaches to the same box, and resumes it if it was paused.

Remove boxes from saved sessions you will not resume.

What are the limits of the Pi extension?

The main limits are the account box cap and the shape your account allows. They come from the Pi docs, the extension README and the Limits page.

• Box cap. Your account caps how many sandboxes are open at once, paused ones included, and how many you create per day. A create over the cap fails rather than queueing.
• Shape. Your account sets the largest shape you can create. If s-2vcpu-2gb is refused, pass a smaller one with --sandbox-shape.
• Bandwidth. Each sandbox gets a 50 GiB bandwidth budget by default, and it can be extended.
• No GPUs. No GPU shapes are offered.

To run several sandboxes that talk to each other, join them with --sandbox-network. Isolation for networked untrusted code covers the model.

When do I not need this?

If you want Pi isolated on your own machine, Pi's guide to running in an isolated environment covers Docker and other local options. Use the CreateOS extension when Pi's tools should act on a separate VM with its own guest kernel.

Common questions

How do I run Pi coding agent tools in a remote sandbox?

Install the CreateOS extension for Pi, sign in with createos login, then start Pi with pi --inside-sandbox. A sandbox is created when the session starts, and Pi's bash, read, write, edit, ls, find and grep tools run inside it.

Does Pi itself run inside the CreateOS sandbox?

No. Pi keeps running on your machine. Only Pi's built-in tools act inside the sandbox, and Pi credentials, settings and sessions stay local.

Why is my project missing from the Pi sandbox?

A fresh sandbox is empty. Start Pi with --sandbox-sync-once to copy the project to /root/workspace once, or --sandbox-watch for a two-way sync all session. The two flags cannot be combined.

Why does the old Pi sandbox flag fail?

The --inside-createos-sandbox flag was retired along with the --createos-* options. It now reports an error and blocks host tools. Use --inside-sandbox and the matching --sandbox-* flags instead.

Can the Pi sandbox reach the internet?

Yes, by default. Egress is open until you set a rule. Ask Pi to call sandbox_firewall with the hosts the work needs. Once any rule is set, everything else is dropped in-kernel on the host, outside the VM.

Does the sandbox keep running after I quit Pi?

Only for a saved session. An ephemeral session destroys its sandbox on exit. A saved session keeps it running so you can resume, and prints a createos sandbox rm command to remove it.

Next step

The Pi docs page has the install command, every tool and every command. Open the CreateOS extension docs for Pi and start your first sandboxed session.

About CreateOS

CreateOS runs AI agents and the code they write. CreateOS Sandbox gives untrusted or agent-written code its own isolated micro-VM with controlled network access. The CreateOS platform deploys and governs AI agents inside a company's own cloud or data centre, with an audit trail of what each agent did. Start at createos.sh.