Dev Server Runbook

Runbook for running and troubleshooting the three local development services.

Dev Server Runbook

Prerequisites: Node.js 22+ and corepack enabled. See Architecture for how the three services interact.

This project runs 3 local services:

• Site: http://localhost:3000
• Content Studio: http://localhost:4100
• Orchestrator: http://localhost:4200

Use the managed workflow commands from repo root.

Start

pnpm dev:start

Check Status

pnpm dev:status

Expected output when healthy:

• running
• pid: ...
• log: .../.run/devctl/dev.log

Note: pnpm dev:status returns exit code 1 when stopped. That is expected.

Restart

pnpm dev:restart

Stop

pnpm dev:stop

Logs

pnpm dev:logs

Full Health Check

curl -sS -o /dev/null -w "3000:%{http_code}\n" http://localhost:3000/
curl -sS -o /dev/null -w "4100:%{http_code}\n" http://localhost:4100/
curl -sS http://localhost:4200/health

Healthy responses:

• 3000:200
• 4100:200
• {"ok":true}

Troubleshooting

1. If site/Content Studio/orchestrator is unreachable:
   • Run pnpm dev:status
   • If stopped, run pnpm dev:start
2. If status says running but UI fails:
   • Run pnpm dev:logs
   • Run the curl health checks above
3. If ports are occupied by stale processes:
   • Run pnpm dev:stop
   • Run pnpm dev:start
4. Deep diagnostics:
   • Run pnpm dev:doctor