Guides

Configuration

Pi-Bolt has no configuration of its own: it reads Pi's. A few environment variables control the Pi-Bolt executable itself, for diagnostics and tuning.

Pi's configuration#

Pi-Bolt and Pi share the agent directory, ~/.pi/agent, and a project's .pi folder:

File or folder	Holds
`settings.json`	Settings: default model, theme, extensions on and off, and more
`auth.json`, `models.json`	Logins and API keys; custom providers and models
`sessions/`	Saved sessions
`extensions/`, `prompts/`	Your extensions and prompt templates
`mcp.json`	MCP servers

Pi's Configuration, Settings and Environment variables pages apply to Pi-Bolt as written. PI_CODING_AGENT_DIR moves the agent directory, and PI_OFFLINE=1 (or --offline) turns off network operations at startup.

Pi-Bolt never changes what Pi loads. It reads the packages in settings.json's packages as Pi does until you install or remove one with pi-bolt; from then on it keeps a list of its own, piBolt.packages (made from packages), which Pi does not read. OpenSec's extensions are only ever in that list. See Pi and Pi-Bolt side by side.

Pi-Bolt's environment variables#

These are read by the Pi-Bolt executable at run time.

Variable	Effect
`PIBOLT_VARIANT`	The build the installer or the npm package installs. See Choose a build.
`PIBOLT_HOME`	npm package: where downloaded builds are kept. Default: `~/.pi-bolt`.
`BUN_AOT=0`	Ignore the compiled code and run Pi from bytecode. Use it to tell whether a problem comes from the compiled code.
`BUN_STATIC_HEAP_VERBOSE=1`	Report how the compiled code and prebuilt heap were loaded.
`PI_TIMING=1`	Pi's startup timings, including each extension's factory.
`PI_TUI_SCROLL_ROWS=0`	Redraw every changed row instead of scrolling rows that only moved, for a terminal that does not scroll a region correctly.
`BUN_CONFIG_HTTP_KEEPALIVE_TIMEOUT=N`	Seconds an idle connection to a server waits to be reused when the server does not say. Default: 4, as in Node.
`BUN_JSC_numberOfGCMarkers=N`	Threads that mark during a garbage collection. Default: 2.
`MIMALLOC_PURGE_HOLES_MIN_INTERVAL=N`	Milliseconds between returns of freed memory to the system. Default: 250. Lower returns memory sooner, for more CPU.
`JITI_FS_CACHE=false`	Do not keep the transpiled source of run-time extensions (kept in `cache/jiti` of the agent directory).

The installer has its own variables; see Installer options.

.env files#

Pi-Bolt does not read a .env file from the working directory. Pi on Bun does, because Bun loads one into every program's environment; Pi on Node does not. A project's .env (its API keys, its proxy settings) belongs to the project. Set what Pi should see in the shell that starts it.