Observability Server
Manage the observability event server lifecycle. Mirrors the CLI subcommands.
Repo root: /Users/nathanvale/code/side-quest-observability Default port: 7483
Subcommand Routing
Route based on $ARGUMENTS:
| Argument | Action |
|----------|--------|
| start | Start the server |
| stop | Stop the server |
| status | Check server health |
| (empty) | Ask the user what they want to do |
start
- Check if a server is already running:
curl -sf http://127.0.0.1:7483/health 2>/dev/null
If healthy, report the existing server and stop -- do not start a second instance.
- Start the server in the background from the repo root:
bun run /Users/nathanvale/code/side-quest-observability/packages/server/src/cli/index.ts start --port 7483 &
- Wait briefly, then verify startup:
sleep 1 && curl -sf http://127.0.0.1:7483/health
- Report to the user:
- Health check result
- Dashboard: http://127.0.0.1:7483
- WebSocket: ws://127.0.0.1:7483/ws
Custom port
If the user specifies a port, pass --port <PORT> and adjust all URLs.
stop
- Check if a server is running:
curl -sf http://127.0.0.1:7483/health 2>/dev/null
If not reachable, report that no server is running and stop.
- Stop the server using the CLI:
bun run /Users/nathanvale/code/side-quest-observability/packages/server/src/cli/index.ts stop
- Verify shutdown -- health endpoint should be unreachable:
curl -sf http://127.0.0.1:7483/health 2>/dev/null
- Report that the server has been stopped.
status
- Hit the health endpoint:
curl -sf http://127.0.0.1:7483/health 2>/dev/null
- If reachable, report the health response (uptime, event counts, port).
- If not reachable, report that no server is running.
Troubleshooting
Port already in use
If start fails with EADDRINUSE, check what's on the port:
lsof -i :7483
Report the conflicting process and ask the user how to proceed.
Server won't stop
If the CLI stop command fails, check the PID file:
cat ~/.cache/side-quest-observability/events.pid
Ask the user before killing the process directly.