Installation Guide

Last updated: 2026-07-13

This guide gets Pi running on your machine from scratch in about five to ten minutes. Pi is an npm-workspaces monorepo, and it installs hardened by default — please follow the steps exactly and do not skip --ignore-scripts.

① Requirements

Make sure your machine has:

• Node.js 18+ (with npm);
• Git (to clone the repo);
• Optional: Docker / Gondolin / OpenShell sandbox (to isolate what the agent may execute — see Running & debugging).

node -v   # needs >= 18
npm -v

② Clone the repository

git clone https://github.com/earendil-works/pi.git
cd pi

The repository is a single npm-workspaces monorepo, so one clone gives you every Pi package — pi-ai, pi-agent-core, pi-coding-agent and pi-tui — without juggling several repos or copy-pasted snippets.

③ Install dependencies safely (supply-chain hardening)

This is the most important step in the whole guide. Pi's package-lock.json is the source of truth and versions are precisely pinned; using --ignore-scripts stops dependencies from running any lifecycle scripts (preinstall / postinstall and friends) during npm install, which eliminates the "install a package and it quietly runs malicious code" attack class.

# dev install (always with --ignore-scripts)
npm install --ignore-scripts

# CI install, equally hardened
npm ci --ignore-scripts

④ Build all packages

npm run build   # build every package in the workspaces
npm run check   # optional: lint + format + type-check

The first build compiles every workspace package; later builds are incremental and much faster. Running npm run check is optional but catches type and lint issues before you launch the agent.

⑤ Configure a model API key

Through pi-ai, Pi unifies many model providers. To let the agent actually call an LLM, set at least one provider's key in an environment variable. Using OpenAI as an example:

export OPENAI_API_KEY="sk-..."
# other providers similarly: ANTHROPIC_API_KEY / GOOGLE_API_KEY / AWS_... etc.

For the full list of supported providers and how to switch between them, see the model providers docs. If you don't have a key yet, you can still run with the built-in MockModel (see the verify step). A practical tip: put your exports in a .env file that you load per shell, rather than pasting keys into every terminal, so they are not leaked into shell history or logs.

⑥ Launch the coding agent

# launch the interactive coding agent from source
./pi-test.sh

Once started you get a terminal interface like a pair programmer: describe a task in English or Chinese and it will read code, edit files and run commands.

⑦ Verify

Send a simple instruction to confirm the chain works:

# in the agent session, type
"describe in one sentence what this directory does"

• If it returns a sensible answer, the model is connected and the install succeeded ✅
• To verify without spending tokens, switch the model to MockModel; it simulates replies locally and exercises the tool and loop logic;
• If launch fails, re-check step ③ (did you drop --ignore-scripts?) and step ⑤ (is the key exported in the shell that launched ./pi-test.sh?).

What you just installed

After the build, your workspace contains the four Pi packages: pi-ai (the unified model API), pi-agent-core (the agent runtime), pi-coding-agent (the CLI you just launched), and pi-tui (the terminal UI library). You can adopt a single package or the whole set — the Core packages page explains what each one owns and where they meet.

Keeping Pi updated

Because installs are pinned and script-disabled, updating is explicit and safe. Pull the latest source and reinstall the same hardened way:

git pull
npm install --ignore-scripts
npm run build

Pi's own pi update --self follows the same principle. If a build error appears after an update, it usually means a Node or lockfile drift — re-run with --ignore-scripts and check the Running & debugging docs. Remember that the lockfile is the source of truth, so never let an installer rewrite it behind your back.