7  Headless “server” mode (RPC)

NoteLearning objective

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

Importantjson and rpc modes read from stdin

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:

  1. Spawns pi --mode rpc (optionally with --provider lmstudio --model …).
  2. Keeps the child’s stdin and stdout pipes open for the process lifetime.
  3. Writes JSON request lines to stdin (prompts, tool permissions, model switches).
  4. 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.
TipExercises
  1. Open docs/rpc.md and docs/json.md from the bundled docs and identify the event types pi emits when it makes a tool call.
  2. 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 -p text mode.
  3. Sketch (in pseudocode) a wrapper that spawns pi --mode rpc, sends one prompt, and prints assistant text events.
  1. Locate the bundled docs with ls "$(npm root -g)/@earendil-works/pi-coding-agent/docs" and open rpc.md and json.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.

  2. 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.

  3. 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.stdin

    The 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.md for the real implementation.