PaperClipAI/packages/paperclip-runner/docs/tutorials/live-console-protocol-server.md

Live console: Run the Protocol Demo Server

What this is

This tutorial runs the Live console server layer. It has no browser UI yet. You can use curl to act like the browser.

The server starts Codex. Codex login data stays on the server. The JSON replies must not contain a Paperclip key, an OpenAI key, or a bearer value.

Step 1: Run deterministic checks

From the repository root, run:

pnpm --filter @paperclipai/paperclip-runner exec vitest run \
  src/drivers/codex/codex-app-server-driver.test.ts \
  src/mock-core/live-console-demo-server.test.ts

Expected result: both files pass. The tests cover requests, goals, lineage, steering, interrupt races, reconnect, replay, and redaction.

Step 2: Start the server

Use an empty directory outside your Codex home:

liveConsole_workspace="$(mktemp -d)"
pnpm --filter @paperclipai/paperclip-runner demo:live-console -- \
  --host 127.0.0.1 \
  --port 4174 \
  --working-directory "$liveConsole_workspace"

Keep this terminal open. The first output line is JSON. It names the host, port, and server-owned working directory. It also says "credentialsExposed":false.

Step 3: Check the boundary

In a second terminal, run:

curl -s http://127.0.0.1:4174/api/liveConsole/health \
  -H 'Origin: http://127.0.0.1:4174' \
  -H 'Sec-Fetch-Site: same-origin' | jq

Expected facts:

• status is ok;
• boundary is package-local-mock-core;
• providerAuthentication is server-side; and
• credentialsExposed is false.

Step 4: Start one safe session

curl -s -X POST http://127.0.0.1:4174/api/liveConsole/sessions \
  -H 'Origin: http://127.0.0.1:4174' \
  -H 'Sec-Fetch-Site: same-origin' \
  -H 'content-type: application/json' \
  --data '{"objective":"Create demo.txt with exactly: liveConsole demo","message":"Complete and verify the exact file task."}' \
  | tee "$liveConsole_workspace/session.json" | jq

Copy sessionId and activeTurnId from the reply. The server ignores a browser-supplied working directory and rejects browser-supplied credential fields.

Step 5: Read live or replayed events

session_id="$(jq -r .sessionId "$liveConsole_workspace/session.json")"
curl -s "http://127.0.0.1:4174/api/liveConsole/sessions/$session_id/events?after=0" \
  -H 'Origin: http://127.0.0.1:4174' \
  -H 'Sec-Fetch-Site: same-origin' | jq

The reply contains canonical PRP events and a cursor. A later request can pass that cursor as after. The same events go through the same reducer during live view and replay.

For a live stream, run:

curl -N "http://127.0.0.1:4174/api/liveConsole/sessions/$session_id/stream?after=0" \
  -H 'Origin: http://127.0.0.1:4174' \
  -H 'Sec-Fetch-Site: same-origin'

Step 6: Reconnect the same session

curl -s -X POST \
  "http://127.0.0.1:4174/api/liveConsole/sessions/$session_id/reconnect" \
  -H 'Origin: http://127.0.0.1:4174' \
  -H 'Sec-Fetch-Site: same-origin' \
  -H 'content-type: application/json' --data '{}' | jq

Confirm that runId, normalizedSessionId, driverSessionId, and providerSessionId did not change. The new events include session.resumed.

The repeated browser headers are intentional admission evidence. DNS-rebinding Hosts, cross-origin or missing Fetch Metadata, wildcard binds, and simple text/plain mutations are rejected. This protects the browser boundary, but untrusted local processes can still make loopback requests; Codex sandbox and approval policy remain the final execution boundary.