Pi + free OpenRouter quickstart

Know the four names

• WorksGood is the product.
• wg is its task-graph, service, and TUI CLI.
• @worksgood/pi is the npm-package identity of the WorksGood Pi integration. Its compatible build is embedded in wg, not fetched separately from npm.
• pi-worksgood is the extension label Pi displays.

Pi itself is the coding-agent runtime installed from @earendil-works/pi-coding-agent. If wg --version prints WireGuard output, stop and resolve the PATH collision below.

1. Install WorksGood and Pi

Install Rust/Cargo and Node.js 22.19 or newer, then run:

cargo install --git https://github.com/graphwork/wg --locked
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
wg --version
pi --version

Pi's documented --ignore-scripts install disables dependency lifecycle scripts; Pi does not need them for a normal install.

2. Authenticate Pi safely

Create a key on OpenRouter's Keys page. Start pi, enter /login, choose Sign in with an API key, choose OpenRouter, and paste the key only into Pi's Enter OpenRouter API key secret prompt.

Never put the key in a command, environment assignment, project file, or shell history. Use a private, unrecorded terminal. Pi stores the login at ~/.pi/agent/auth.json with mode 0600; never print or commit it.

The first model probe in the next step is the exact point that requires this login.

3. Discover a current free model, then prove it works

OpenRouter's live public catalog is authoritative. Free-model availability, limits, expiration, context, provider capacity, and actual tool support all change. No model on this page is a permanent default.

curl -fsSL 'https://openrouter.ai/api/v1/models?supported_parameters=tools' |
  jq -r '.data[]
    | select(.id | endswith(":free"))
    | select((.architecture.input_modalities // []) | index("text"))
    | select((.context_length // 0) >= 65536)
    | select((.supported_parameters // []) | index("tools"))
    | select((.pricing.prompt | tonumber?) == 0)
    | select((.pricing.completion | tonumber?) == 0)
    | [.id, (.context_length | tostring), (.expiration_date // "-")]
    | @tsv'

The output is model ID, context length, and expiration. Install jq with your package manager, or use OpenRouter Models and its Free/tool filters. Catalog metadata is advisory, so validate the exact choice through Pi before persisting it:

read -r -p 'Paste one current :free model ID: ' MODEL
pi update --models
pi --list-models openrouter | grep -F "$MODEL"
printf 'pi-openrouter-tool-probe\n' > .pi-model-probe.txt
pi --provider openrouter --model "$MODEL" -p \
  'Use the read tool to read .pi-model-probe.txt, then reply with only its text.'
rm .pi-model-probe.txt

Expected final text: pi-openrouter-tool-probe. If listing, auth, limits, availability, or the read-tool call fails, choose another current candidate. For example, nvidia/nemotron-3-ultra-550b-a55b:free matched on 2026-07-18; that is a dated example, not an eternal default. The random openrouter/free router is not a pinned, reproducible WG route.

4. Initialize a fresh project and select Pi explicitly

Run this in the same shell where MODEL was set. It deliberately keeps both strong worker work and weak agency/meta work on the execution system you chose.

mkdir -p ~/work/my-wg-project
cd ~/work/my-wg-project
wg init

wg pi-plugin install
WG_MODEL="pi:openrouter:$MODEL"
wg profile pi --strong "$WG_MODEL" --weak "$WG_MODEL"
wg profile use pi --no-reload

wg pi-plugin status
wg profile show
wg config --models

wg service start
wg service status
wg tui

Expected readiness signals:

console wired:    yes
Active named profile: pi *
MODEL ... pi:openrouter:<the model you tested>   HANDLER pi
Service: running

wg init is graph-only until the profile commands explicitly select Pi. wg tui is also only a graph viewer: opening it does not initialize, authenticate, select OpenRouter, change a profile/model, or start the service.

Already configured?

Do not run the fresh-profile block blindly. Inspect first:

wg profile show
wg config --list
wg config --models
wg config lint

Then use wg setup to review scope and changes, or deliberately edit your named profile. wg profile use is an authoritative global activation and may back up/clear project-local routing pins that would shadow it.

5. Verify pi-worksgood

wg pi-plugin install materializes the compatibility-locked @worksgood/pi build embedded in your installed wg and adds its absolute path to Pi settings. It is idempotent. wg pi-plugin status should report build ready: yes and console wired: yes. Restart Pi or use /reload; its extension list should show exactly pi-worksgood.

Standalone Pi uses that settings entry. WG-spawned Pi workers are hermetic instead: WG passes the exact embedded/cache extension by absolute pi -e path with ordinary discovery disabled. Hermetic workers do not depend on a global npm package or the standalone-console entry.

Legacy @worksgood/wg-pi-plugin or old .../wg/pi-plugin/.../dist/index.js settings are migrated by wg pi-plugin install. After Pi visibly loads one pi-worksgood, follow the one-time removal notice (normally pi remove npm:@worksgood/wg-pi-plugin).

6. Optional web capabilities

Pi packages run with your full user permissions. Review third-party source first.

Search and readable content

pi install npm:pi-web-access@0.13.0

pi-web-access provides web search, readable page/PDF content extraction, GitHub cloning, and optional video analysis. Use it when you need sources or content, not control of a rendered UI.

Interactive browser automation

npm install -g agent-browser@0.32.2
agent-browser install --with-deps
pi install npm:pi-agent-browser-native@0.2.70
npm exec --yes --package pi-agent-browser-native@0.2.70 -- pi-agent-browser-doctor

On macOS use agent-browser install without --with-deps. This tested pairing is pinned because wrapper 0.2.70 audits agent-browser 0.32.2 exactly and its doctor rejects version drift; agent-browser's npm engine requires Node.js 24+. Consult the wrapper's current README/support matrix before upgrading either side.

Browser automation is for DOM inspection, clicks, forms, screenshots, downloads, authenticated profiles, and live UI QA. It is heavier and exposes visible page/profile content to the model. Neither package bypasses CAPTCHAs or site policy.

Service operations

wg service status
wg service restart
wg service status
wg tui

Restart preserves the selected profile/model but does not log Pi in. Existing workers keep their model; newly spawned workers receive a newly activated profile. Stop with wg service stop.

Platform notes

• Linux: the full graph/plugin/profile/service sequence was tested in isolated HOME/project directories. Browser --with-deps may invoke the system package manager.
• macOS: WG, Pi, OpenRouter, and pi install commands are the same. Use brew install jq; omit browser --with-deps.
• Termux: Pi documents GitHub/F-Droid Termux + Termux:API, then pkg install nodejs termux-api git and the same Pi npm install. Use pkg install jq. Pi has no image clipboard there. WorksGood does not currently publish an Android/Termux release target, and this page does not claim the desktop Chromium add-on works there.

Troubleshooting

PATH or the wrong wg

command -v wg pi node npm
wg --version
pi --version

Cargo normally installs to ~/.cargo/bin. npm reports its prefix with npm prefix -g. Put the corresponding executable directories on PATH and open a new shell. If wg is WireGuard, do not overwrite it with --force; invoke WorksGood by a verified absolute Cargo path or use a private bin directory and resolve the collision deliberately.

Failed to run wg: No such file or directory

cargo install --git https://github.com/graphwork/wg --locked
wg --version
wg dev-check
wg service restart
wg tui

Close the old TUI and start the newly installed binary. If it persists, preserve command -v wg, version output, and .wg/service/ logs for diagnosis.

Pi is missing

command -v pi
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

Confirm Node.js 22.19+ and npm's global executable directory on PATH, then restart WG.

Plugin missing, stale, or duplicated

wg pi-plugin status
wg pi-plugin install
wg pi-plugin status

Restart Pi and look for exactly one pi-worksgood. Do not install npm:@worksgood/pi; WG carries its matching build.

Model absent, limited, or no longer free

Repeat the live catalog filter and Pi tool probe, then deliberately update both profile tiers. :free never promises permanent availability, unlimited use, fixed context, or reliable tools.

OpenRouter authentication fails

In Pi, repeat /login → API key → OpenRouter. Do not pass the key on a command line. “No models available” or “No API key found for openrouter” means login did not succeed in that HOME. Check permissions without printing the file:

ls -l ~/.pi/agent/auth.json

If a key was exposed, revoke it in OpenRouter and create a replacement. Pi's OpenRouter login is separate from WG-native endpoint secrets; pi:openrouter:... intentionally uses Pi-owned authentication.