Skip to content

Pi

Run Pi coding agent with agentkernel for isolated code execution.

Quick Start

Pi is an open-source coding agent with its own extension system. The agentkernel extension overrides Pi's built-in bash tool so every shell command runs in a microVM sandbox instead of on your machine.

# 1. Start agentkernel API server (pick one)
brew services start agentkernel   # runs in background, survives reboots
agentkernel serve                 # or run manually in a terminal

# 2. Install the extension (pick one)
pi install npm:pi-agentkernel     # via Pi's package manager (recommended)
agentkernel plugin install pi     # or via agentkernel CLI

# 3. Launch Pi — the extension loads automatically
pi

Supported Pi host

Use Pi >=1.0.1 <2; npm installations require Node.js >=22.19.0. Pi 0.x and 1.0.0 are no longer supported. Pi 1.0.1 fixes the vulnerable brace-expansion dependency. This requirement applies to both extension installation methods above.

Updating the extension does not upgrade an existing Pi host. Update Pi using its original installer or package manager (pi update for managed installations). For a global npm installation, run:

npm install -g --ignore-scripts '@earendil-works/pi-coding-agent@^1.0.1'
pi --version

Check that pi --version reports at least 1.0.1 and below 2 before loading the extension.

Extension Integration

Unlike MCP-based agents, Pi uses a native extension that replaces the built-in bash tool. When the extension loads:

  1. A persistent sandbox is created for the session
  2. Every bash call the LLM makes runs inside that sandbox via POST /sandboxes/{name}/exec
  3. State persists between calls — installed packages and files carry over
  4. The sandbox is removed when the session ends

If agentkernel is not running, the extension falls back to local execution.

The extension also provides:

Tool Description
bash Built-in tool override — routes all shell commands through the sandbox
sandbox_run One-shot command in a fresh sandbox (clean environment each time)
Command Description
/sandbox Show current sandbox status

Install

Via Pi's package manager (recommended): 

pi install npm:pi-agentkernel

Or via agentkernel CLI: 

agentkernel plugin install pi

The first method installs globally. The second creates .pi/extensions/agentkernel/ in your project.

Setup

1. Install agentkernel

brew tap thrashr888/tap && brew install agentkernel
# Or: curl -fsSL https://raw.githubusercontent.com/thrashr888/agentkernel/main/install.sh | sh

2. Install the extension

agentkernel plugin install pi

Your project should have:

.pi/
  extensions/
    agentkernel/
      index.ts          # Extension source
      package.json      # Metadata

3. Start agentkernel

# As a background service (recommended — survives reboots)
brew services start agentkernel

# Or run manually
agentkernel serve --host 127.0.0.1 --port 18888

4. Launch Pi

pi

The extension loads automatically and notifies when the sandbox is ready.

API Keys

Pi supports multiple LLM providers. Pass your provider's API key as usual — it stays on your machine and is not forwarded to the sandbox:

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Google
export GOOGLE_API_KEY=AI...

Sandbox-Based Workflow

You can also run Pi itself inside an isolated sandbox container:

# Create sandbox with Pi pre-installed
agentkernel sandbox create pi-dev --config examples/agents/pi/agentkernel.toml

# Start the sandbox
agentkernel sandbox start pi-dev

# Run Pi inside the sandbox
agentkernel attach pi-dev
# Inside the sandbox:
pi

Configuration

Example config at examples/agents/pi/agentkernel.toml:

[sandbox]
name = "pi-sandbox"

[build]
dockerfile = "Dockerfile"

[agent]
preferred = "pi"
compatibility_mode = "pi"

[resources]
vcpus = 2
memory_mb = 1024

[security]
profile = "moderate"
network = true      # Pi needs network for LLM API calls
mount_cwd = true    # Mount project directory

Environment Variables

Variable Default Description
AGENTKERNEL_BASE_URL http://localhost:18888 agentkernel API endpoint
AGENTKERNEL_API_KEY - Optional Bearer token for API auth

Pi itself supports multiple LLM providers. Pass your provider's API key as usual — it stays on your machine and is not forwarded to the sandbox.

What's Included

The sandbox image includes:

  • Node.js 24 LTS — Runtime for Pi
  • Pi CLI — @earendil-works/pi-coding-agent
  • Git — Version control
  • Python 3 — For Python projects
  • ripgrep — Fast code search
  • fd — Fast file finder
  • jq — JSON processing

Customizing

Create a custom Dockerfile based on the example:

FROM node:24-alpine3.24

# Base tools
RUN apk add --no-cache git bash python3 ripgrep fd jq

# Pi CLI
RUN npm install -g @earendil-works/pi-coding-agent@1.0.1

# Your additions
RUN apk add --no-cache rust cargo

# Setup
WORKDIR /workspace
USER developer

Embedding the minimum Pi host

Fresh Pi 1.0.1 installations have an upstream unbundled-library incompatibility with newer codemode dependencies. Prefer the current supported 1.x host for new installations. Applications that must embed 1.0.1 should use the documented scoped root override and locked install recipe. The bundled CLI version check still works; updating the AgentKernel extension does not upgrade an existing Pi host. The supported minimum remains 1.0.1.