7 Headless “server” mode (RPC)
You understand pi’s non-interactive output modes (text, json, and rpc), and you can decide which to use for scripting versus for embedding pi as a programmatic backend.
7.1 “PI Server” demystified
Newcomers often ask how to run pi “as a server”. pi is not a long-running network daemon you point a browser at; its headless story is the --mode flag, which changes how a single pi process talks to whatever is driving it:
| Mode | Output | Use it for |
|---|---|---|
text (default) |
Human-readable text | Interactive use and one-shot -p prompts |
json |
Structured JSON events | Scripting that needs to parse what happened |
rpc |
JSON-over-stdin/stdout protocol | Embedding pi as a backend in other programs |
So a “pi server”, in the sense of something a program can drive, is pi --mode rpc (remote procedure call): your program writes JSON (JavaScript Object Notation) commands to pi’s stdin and reads JSON events from its stdout. This is how you would wire a local-model pi into an editor plugin or a service, all still running against LM Studio with no cloud involved.
7.2 The crucial gotcha
Both --mode json and --mode rpc expect to be driven over stdin. If you run, say, pi -p --mode json "do something" from a script with no stdin attached, pi reaches end-of-input immediately, emits nothing, and exits. That is not a model or network failure; it is the protocol working as designed. For one-shot prompts you want text mode (-p, the default); reserve json/rpc for programs that keep a pipe open and speak the protocol. This trips up almost everyone once; see Chapter 8.
7.3 A mental model for driving rpc
A controlling program typically:
- Spawns
pi --mode rpc(optionally with--provider lmstudio --model …). - Keeps the child’s stdin and stdout pipes open for the process lifetime.
- Writes JSON request lines to stdin (prompts, tool permissions, model switches).
- Reads JSON event lines from stdout (text deltas, tool calls, completion).
The exact message schema is documented in the package’s docs/rpc.md and docs/json.md (ls "$(npm root -g)/@earendil-works/pi-coding-agent/docs"), and is the most reliable reference because it matches your installed version. For most users building automation, the simplest robust option is still pi -p text mode wrapped in a shell script; reach for rpc only when you are building an interactive integration.
7.4 When to use which
- A nightly script that asks the local model to summarize a repo:
pi -p(text). - A pipeline step that must branch on what tools ran →
pi -p --mode json, parsing the event stream. - An editor plugin / desktop app embedding pi:
pi --mode rpc, holding the pipes open.
- Open
docs/rpc.mdanddocs/json.mdfrom the bundled docs and identify the event types pi emits when it makes a tool call. - Reproduce the gotcha: run
pi -p --mode json --offline --provider lmstudio --model qwen3-coder-30b-a3b-instruct "hi"with no stdin and confirm you get no output. Then run the same prompt in plain-ptext mode. - Sketch (in pseudocode) a wrapper that spawns
pi --mode rpc, sends one prompt, and prints assistant text events.
Locate the bundled docs with
ls "$(npm root -g)/@earendil-works/pi-coding-agent/docs"and openrpc.mdandjson.md. The exact names match your installed version, which is why these files (rather than memory) are the reliable reference. You are looking for the events emitted around a tool call: a tool-call event carrying the tool name and its arguments, followed later by a tool-result/completion event. Text output arrives as a stream of text-delta events, and the run ends with a completion event. Note the precise field names from your local copy, since they are version-specific.With no stdin attached,
pi -p --mode json --offline --provider lmstudio --model qwen3-coder-30b-a3b-instruct "hi"produces no output and exits: json mode reads commands from stdin, hits end-of-file (EOF) immediately, and stops. This is the protocol working as designed, not a model or network failure. Running the same prompt in plain text mode,pi -p --offline --provider lmstudio --model qwen3-coder-30b-a3b-instruct "hi", returns a normal answer, confirming that the silence was the mode and not the setup.A minimal wrapper, in pseudocode:
proc = spawn("pi", ["--mode", "rpc", "--provider", "lmstudio", "--model", "qwen3-coder-30b-a3b-instruct"]) keep proc.stdin and proc.stdout open write JSON request line to proc.stdin: { type: "prompt", text: "Summarize this repo" } for each line read from proc.stdout: event = parse_json(line) if event is an assistant text delta: print event.text if event signals completion: break close proc.stdinThe key points are: hold both pipes open for the process lifetime, write newline-delimited JSON requests, and read newline-delimited JSON events, printing only the assistant text deltas and stopping on the completion event. Use the field names from your local
docs/rpc.mdfor the real implementation.