Stack

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

Documents Stack 0.2.0-dev.20260703.2 hosted, inference, Lights, and gardener behavior. See Stack Changelog for the current release state.

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 public nightly alpha. It runs locally without Synth signup. Sign in when you want hosted Synth features such as remote workers, hosted optimizer runs, Research Factories, remote sync receipts, or org-backed Synth inference.

Current nightly: 0.2.0-dev.20260703.2 — the Monitor Gardener Goal release, with /lights on, scrollable/filterable threads, gardener core focus, goal-mode worker chat, and durable gardener thread tools.

Public docs: Quickstart · Local-only · Connect Synth · Hosted ops · Goal mode & monitor · Cockpit · Stack MCP

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.
Local to cloud sync	Remote state is observed through typed stackd snapshots and receipts, not by scraping cloud storage.
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

Nightly (macOS Apple Silicon):

curl -fsSL https://stack.usesynth.ai/install.sh | sh
stack --version
stack doctor
stack demo

From source (requires Bun):

git clone [e-mail]: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.

export SYNTH_API_KEY="sk_..."

Local-only use remains valid without that key. See Local-only mode and Connect Synth.

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.

See also Stack MCP for the full tool surface in the cockpit.

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:

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 on the nightly channel for macOS Apple Silicon. See Changelog for release notes. External beta expands package-manager channels once install/update proofs are complete for each surface.