> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# stackd local API

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

<Note>
  Documents Stack **`0.2.0-dev.20260701.1`**. Monitor scheduler and telemetry routes
  added in the [2026-07-01 release](/stack/changelog).
</Note>

**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:

```bash theme={null}
./bin/stackd serve
curl -s http://127.0.0.1:8792/health
```

## MCP over HTTP

When healthy, stackd hosts **Stack MCP** at:

```text theme={null}
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

```bash theme={null}
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](/stack/quickstart#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`, `GET /telemetry/crashes`   | Local telemetry surfaces           |
| `GET /doc`, `/openapi.json`                         | OpenAPI                            |

Monitor control:

```text theme={null}
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](/stack/goal-mode).

## 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](/stack/mcp) — stdio and HTTP MCP tools
* [Configuration](/stack/configuration) — `stack.config.json`