> ## 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.

# Stack

> Use Stack as a local operator cockpit for Synth agents, handoffs, and run evidence.

Stack is a local operator cockpit for working with Synth from coding agents. It
keeps long-running agent work observable, gives operators one place to inspect
runs and handoffs, and connects agent clients to Synth through typed server
surfaces instead of ad hoc file edits.

**Top priority:** Stack is built to make research engineers hyper-productive with the
**full Synth stack** — OSS (local GEPA, StackEval, synth-dev) and hosted (`synth-ai`,
`usesynth.ai` SMR/Factory/optimizers) — from one environment-aware cockpit.

Stack is currently in an internal alpha channel. It runs locally without Synth
signup. Sign in when you want hosted Synth features such as remote workers,
hosted optimizer runs, or org-backed receipts. Public installer paths will be
listed here after those release channels are live.

## What Stack Is For

| Use Stack for                       | Why it matters                                                                                                    |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Synth OSS + hosted in one place** | Local GEPA, StackEval, and usesynth.ai SMR/Factory/optimizers without switching tools.                            |
| Agent run monitoring                | See worker status, messages, and operator events while Codex, Cursor, or other agents work.                       |
| Handoffs                            | Preserve continuity across fresh agent threads through handoff artifacts rather than replaying whole transcripts. |
| Synth MCP access                    | Expose Synth operations through configured tools with explicit permissions and environment selection.             |
| Local first run                     | Run a local demo, emit a receipt, and inspect the work product without signup.                                    |
| Local release checks                | Run local quality and smoke commands before moving a Stack build through private release gates.                   |

## Architecture Boundary

Stack follows a server/client split:

* Rust owns core logic, local persistence, state transitions, and stackd APIs.
* TypeScript owns rendering, keyboard and mouse interaction, and operator UX.
* The TUI calls stackd through typed client APIs; it should not directly write
  Stack persistence files.

That boundary is part of the product contract. It is especially important for
handoffs, where stackd creates and updates meta-thread manifests, handoff JSON,
handoff artifacts, sessions, and event projections.

## Current Install Channel

For the internal alpha, install from the Stack repository:

```bash theme={null}
git clone git@github.com:synth-laboratories/stack.git
cd stack
make install
stack --version
stack doctor
stack demo
stack update --check --manifest packaging/manifests/nightly.example.json
```

`stack doctor` reports local readiness without printing secrets. `stack demo`
runs locally and writes a receipt under `.stack/runs/<run_id>/receipt.json`.
`stack update --check` is read-only; it verifies manifest and platform-target
resolution before installer downloads are published.

Set `SYNTH_API_KEY` before using hosted Synth-backed tools. Keep secrets in your
local environment or agent configuration; do not paste them into prompts or
logs.

```bash theme={null}
export SYNTH_API_KEY="sk_..."
```

## Agent Client Setup

Stack ships local agent integration helpers for Codex-oriented workflows. After
installation, verify that the Stack skills and MCP bridge are available from the
agent client you intend to use.

For hosted Managed Research MCP without the Stack cockpit, use
[MCP Quickstart](/managed-research/mcp-quickstart).

## Handoffs

Stack handoffs are designed for long-running coding work where a fresh agent
thread should continue from a reviewed artifact instead of inheriting a full
parent transcript.

The invariant is:

```text theme={null}
thread = execution
meta-thread = continuity
handoff artifact = parent-to-child transition
successor = new thread id
```

At handoff time, stackd seals the current segment, writes a handoff artifact,
and starts the successor from approved artifacts only. Model and effort changes
happen at the successor boundary, not by mutating a running worker in place.

## Release Quality

Public Stack releases should prove:

* install commands match the documented release channel;
* first run works locally without Synth signup;
* every meaningful local run leaves an inspectable receipt;
* stackd server responses match the TypeScript client contract;
* handoffs create fresh child threads without replaying parent stdout;
* TUI flows remain usable under navigation, resize, and handoff state changes;
* update checks are explicit and do not mutate running agents without operator
  confirmation.

Detailed private launch gates and dogfood evidence are tracked outside the
public docs. Public docs stay focused on the commands and behavior users can
verify.

## Status

Stack is available to internal Synth operators first. External beta docs will
add package-manager installation, release notes, and support expectations once
those channels are live.