Skip to main content
Documents Stack 0.2.0-dev.20260701.1. Monitor scheduler and telemetry routes added in the 2026-07-01 release.
stackd is Stack’s local control plane. It indexes threads, serves Stack MCP, owns local persistence (meta-threads, handoffs, receipts), and exposes HTTP APIs the TUI and MCP clients call. Codex still owns JSONL transcripts under ~/.codex/sessions/. Stack projects those transcripts into typed stackd views — it does not replace Codex as the transcript owner.

​
Auto-start

./bin/stack starts stackd when /health is unavailable, sets STACK_API_URL=http://127.0.0.1:8792, and continues in degraded mode if startup fails. Logs: .stack/runtime/stackd.log. Manual serve: 
./bin/stackd serve
curl -s http://127.0.0.1:8792/health

​
MCP over HTTP

When healthy, stackd hosts Stack MCP at: 
http://127.0.0.1:8792/mcp
Discovery: /.well-known/mcp.json (also linked from /health as mcp_url). Cursor and other MCP clients can attach to that URL instead of stdio ./bin/stack-mcp. Disable with STACKD_MCP=0.

​
Operator CLI

stack crashes --json
stack crashes --remote --json
stack telemetry digest --remote --json
curl -s http://127.0.0.1:8792/telemetry/status
Crash reporting requires backend routes when using --remote. See Telemetry in Quickstart.

​
Core routes (L1)

RoutePurpose
GET /healthLiveness + mcp_url
GET /threads, GET /threads/:idThread index and detail
GET /threads/:id/eventsThread event log
GET /events/streamSSE feed for TUI and monitor
POST /threads/:id/eventsAppend core or meta events (typed)
GET /threads/:id/trace, GET /threads/:id/exportTrace and export bundle
GET /telemetry/status, GET /telemetry/crashesLocal telemetry surfaces
GET /doc, /openapi.jsonOpenAPI
Monitor control: 
POST /threads/:id/monitors/:monitorId/pause
POST /threads/:id/monitors/:monitorId/resume
POST /threads/:id/monitors/:monitorId/mode

​
Local persistence

stackd owns writes to:
  • .stack/events/threads/<session-id>.jsonl — agent and monitor events
  • .stack/meta-threads/**, handoff JSON, successor sessions
  • .stack/actors/<session-id>/monitors/ — monitor checkpoints
  • .stack/exports/<session-id>/ — export bundles
Do not hand-edit these while stackd is running. Use stackd APIs or the TUI.

​
Monitor scheduler

By default stackd runs a monitor scheduler over the event log: it dedupes wake triggers, advances checkpoints, and emits monitor.wake, monitor.summary, and related events when non-TUI producers append core events.
EnvEffect
STACKD_MONITOR_SCHEDULER=0Disable scheduler
STACKD_MONITOR_POLL_MS=<ms>Tune poll interval
See Goal mode & monitor.

​
Bind and port

EnvDefault
STACK_API_BIND127.0.0.1 (use 0.0.0.0 only with intent)
STACK_API_PORT8792
STACK_ROOTApp root for stackd data resolution

​
Next