Guides

Integrations

Anything that runs Pi can run Pi-Bolt: it takes the same arguments, speaks the same JSON and RPC protocols, and reads the same configuration. Point the tool at pi-bolt instead of pi.

Tools that start Pi#

Agent managers, editors and web interfaces start Pi by running a command, usually pi. Most let you set that command. Set it to pi-bolt, or to the full path that command -v pi-bolt prints.

A tool that bundles its own copy of Pi, locked to a version, runs that copy and not Pi-Bolt, unless it lets you choose the Pi executable.

Paseo#

Paseo runs Pi through its pi provider. To run every Pi agent on Pi-Bolt, change that provider's command in ~/.paseo/config.json:

{ "agents": { "providers": { "pi": { "command": ["pi-bolt"] } } } }

Or add Pi-Bolt as a provider of its own, next to Pi. "extends": "pi" tells Paseo to drive it the way it drives Pi; command only changes the executable:

{
  "agents": {
    "providers": {
      "pi-bolt": { "extends": "pi", "label": "Pi-Bolt", "command": ["pi-bolt"] }
    }
  }
}

Restart Paseo, then pick Pi-Bolt in the app or run paseo run --provider pi-bolt "your task".

Scripts and automation#

Pi's non-interactive modes work as documented by Pi:

$ pi-bolt -p "Summarize the open TODOs"           # print mode: answer, then exit
$ pi-bolt -p --mode json "Run the tests"         # a stream of JSON events
$ pi-bolt --mode rpc                              # controlled by another program over stdio

See Pi's CLI, JSON and RPC references. A one-shot pi-bolt -p starts and finishes several times faster than Pi on Bun or Node, which adds up in scripts and CI.

Pi's TypeScript SDK embeds Pi in your own program; that program runs on its own runtime, not on Pi-Bolt.

tmux and terminal multiplexers#

Pi-Bolt runs in tmux, zmx and other multiplexers as Pi does. It also writes less to the terminal: on Linux a session in tmux takes about 28 MB of Pi-Bolt's own memory, against 87 MB for Pi on Bun. See Pi's Run Pi in tmux for tmux settings.

If a terminal draws the screen wrongly while the interface scrolls, start Pi-Bolt with PI_TUI_SCROLL_ROWS=0, which redraws changed rows instead of scrolling them. tmux, zmx, xterm, kitty, Ghostty and VTE terminals do not need it.

Containers#

Pi-Bolt needs nothing from a Linux image but glibc 2.17 or later. The installer also needs curl or wget, and tar. Install it in the image with PIBOLT_YES=1, which takes the defaults without asking:

RUN curl -fsSL https://pi-bolt.opensec.in/install.sh | PIBOLT_YES=1 sh
ENV PATH="/root/.local/bin:$PATH"

Memory limits. Count the executable too: its code is file-backed memory that the kernel charges to the container. Pi-Bolt runs with a limit of about 100 MB, at twice the CPU and with pauses; 256 MB or more leaves it alone.
CPU limits. With --cpus, Pi-Bolt starts fewer threads.
Address-space limits. The compiled code needs about 10 GB of virtual address space. It is reserved, not used. Under a tighter ulimit -v, Pi-Bolt runs from bytecode, more slowly; see Notices at startup.

Pi's Isolate Pi covers running the agent in a container safely.