Stackd local API

Stack’s localhost control plane — threads, events, MCP, telemetry, and exports.

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
curl -s -X POST http://127.0.0.1:8792/telemetry/flush

Crash reporting requires backend routes when using --remote. See Telemetry in Quickstart.

Core routes (L1)

Route	Purpose
GET /health	Liveness + mcp_url
GET /threads, GET /threads/:id	Thread index and detail
GET /threads/:id/events	Thread event log
GET /events/stream	SSE feed for TUI and monitor
POST /threads/:id/events	Append core or meta events (typed)
GET /threads/:id/trace, GET /threads/:id/export	Trace and export bundle
GET /telemetry/status, POST /telemetry/config, POST /telemetry/events, POST /telemetry/flush, GET /telemetry/crashes	Local telemetry surfaces
GET /doc, /openapi.json	OpenAPI

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.

Env	Effect
STACKD_MONITOR_SCHEDULER=0	Disable scheduler
STACKD_MONITOR_POLL_MS=<ms>	Tune poll interval

See Goal mode & monitor.

Bind and port

Env	Default
STACK_API_BIND	127.0.0.1 (use 0.0.0.0 only with intent)
STACK_API_PORT	8792
STACK_ROOT	App root for stackd data resolution

Next

• Stack MCP — stdio and HTTP MCP tools
• Configuration — stack.config.json