pi-outpost

A web chat UI for the pi coding agent — streaming replies, collapsible thinking, live tool cards (bash, edit, …), a file browser, git integration, and a conversation tree you can branch from.

npx pi-outpost init   # writes a starter pi-outpost.config.json here
npx pi-outpost        # http://127.0.0.1:3141/

Requires Node ≥ 24 and a model credential (~/.pi/agent/auth.json, a provider variable like ANTHROPIC_API_KEY, or the setup screen). The default embedded runtime already carries the pi coding agent; a separate pi executable is needed only when agentRuntime.mode is "rpc".

It will not start without a configuration file

That is deliberate. The config decides the agent's working directory, which tools it gets, and whether it can write files or run bash — and inferring that from whatever directory you happen to be standing in is not a decision anyone wants made for them. init writes the safe version (read-only, no bash) for you to open up as needed.

Configuration

The first of these that exists is read, and only that one — configurations are never merged, so the file you are reading is the configuration that is running:

1. --config <path>
2. --profile <name> → <user config dir>/profiles/<name>.json
3. $PI_OUTPOST_CONFIG
4. $PI_OUTPOST_PROFILE → <user config dir>/profiles/<name>.json
5. ./pi-outpost.config.json
6. <user config dir>/config.json

<user config dir> is $XDG_CONFIG_HOME/pi-outpost, or ~/.config/pi-outpost. Not sure which one won, or why a setting has the value it has? pi-outpost config prints the resolved configuration and the file it came from, without starting anything.

Profiles let you configure once and run anywhere: pi-outpost --profile work reads ~/.config/pi-outpost/profiles/work.json, from any directory. A profile is an ordinary config file.

Precedence, for any setting that appears in more than one place: flag > environment variable > config file > default.

| Flag | Effect | |------|--------| | --config <path> | Configuration file to use | | --profile <name> | Named profile from the user config directory | | --cwd <dir> | Directory the agent works in | | --agent-dir <dir> | pi config/session store (default ~/.pi/agent) | | --port <n> / --host <addr> | Where to listen (default 127.0.0.1:3141) | | --offline | Never fetch remote model catalogs | | --open / --no-open | Whether to open the interface once listening | | --open-in window\|browser | Open in a standalone window (default) or a browser tab |

Environment: PI_OUTPOST_PORT (falls back to PORT), PI_OUTPOST_HOST, PI_OUTPOST_CWD, PI_OUTPOST_AGENT_DIR, PI_OUTPOST_TOKEN, PI_OFFLINE.

Security

The agent has file and (optionally) bash tools. The server binds to 127.0.0.1 by default and validates the WebSocket Origin.

• There is no --token flag on purpose: a secret on the command line is readable by anyone who can list processes. Use PI_OUTPOST_TOKEN or the file's server.token.
• Binding off loopback (--host 0.0.0.0) requires a token — the server refuses to start otherwise, because the agent's tools would be reachable by anything that can route to the host.
• Sandbox the agent (sandbox.root, allowWrite, allowBash) for anything beyond your own machine. The effective sandbox is printed at every start.

Full documentation: github.com/laurentftech/pi-outpost.

License

MIT