Patrick Buckley
0cdb679892
* refactor(session): ask the shared supersession predicate at the older sites ``_check_cancelled`` and ``_compaction_event`` predate ``_generation_superseded`` and each carried its own inline copy of the formula, so the drift the helper exists to prevent had two live places to start from. Both are behaviour-identical today. What the pin protects is the generation-0 convention: a bare ``!=`` reads a direct seam caller as an orphan, which would raise a cancel on a live turn and stamp a live compaction superseded — suppressing the end notice, so an operator watching a real compaction fail would be told nothing at all. * fix(session): render a wire-prep fault's cause class, never its message Every other branch of the fatal formatter tails the backend's own diagnostic text, which is what the operator needs. This branch is different in kind: ``prepare_wire`` is our lowering over the session's stored history, so its exception message can quote that history — and the formatted string is both shown to the operator and persisted to ``last_error``, which a coordinating agent reads. ``redact_credentials`` is a best-effort regex by its own docstring, so it is no floor for arbitrary conversation text. The cause's class still identifies the fault, the guidance is unchanged, and the debug traceback logged in the same function localizes the raise site. * feat(console): surface the server-side reasoning parser capability The inline think-tag scan is a fallback for inference servers with no reasoning parser, and for misconfigured ones. An operator running vLLM or llama.cpp with a parser configured had no way to say so from the model shelf — ``server_parses_reasoning`` was reachable only by hand editing the raw capabilities JSON, and it defaults to off, so the scan stays on and both channels run at once. The tile test is a general invariant rather than a single-key pin: every tile key must render a checkbox, carry a default, and — where the key is a ``ModelCapabilities`` field — agree with the dataclass. The matrix is a hand-maintained mirror, so it drifts silently otherwise. * fix(model_turn): a wire-prep wrapper carries the cause's class, not its text Withholding the message in the fatal formatter was not enough. The wrapper was built as ``WirePreparationError(str(prep_err))``, so ``str(exc)`` IS the cause's message — and the interactive retry arm renders exactly that into the dashboard SSE, one line after the formatter emitted the redacted version. ``sanitize_error_text`` is no floor there: it returns arbitrary stored-history text unchanged. Fixing the exception rather than the one consumer closes every caller that stringifies it, now and later. The message still rides ``__cause__`` for tracebacks and debug logs. * fix(console): coerce lifted capability values the way the backend does The tile lift used bare ``!!``, but the capabilities dict is hand-edited JSON: a stored string "false" is truthy to JS while ``apply_capability_overrides`` reads it as False. Opening such a row rendered the tile CHECKED and saving persisted boolean true — inverting the capability without the operator touching it. For ``server_parses_reasoning`` that silently disables the inline tag scan, the exact typo model_turn's comment already warns about, and this key had just been lifted into the matrix. ``_capBool`` mirrors the backend's spelling table; a value the backend would not coerce stays in the raw JSON rather than being rewritten, which is the policy the modal already applies to thinking_mode. Cases are generated from the Python table and executed under node, so a spelling added on one side fails here. Also tightens two pins the tile test left open: the checkbox must render inside the container the JS actually queries, and a tile key that is not a capability field is exempted by NAME rather than by a blanket hasattr, which was swallowing the consistent-rename case. * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Turnstone
Self-hosted, local-first orchestration for tool-using AI agents. Give LLMs real tools — shell, files, search, web — and run them across your own cluster with direct HTTP routing and interactive interfaces. Your code, your models, your data stay on hardware you control: no telemetry, no phone-home.
Named after the Ruddy Turnstone (Arenaria interpres) — a shorebird that flips stones to discover what's hiding underneath.
What is a harness?
ℋ : s_{n+1} ~ T(s_n) for n < τ_H
the primer → · the formalism →
Release Tracks
| Track | Install | Docker | Description |
|---|---|---|---|
| Stable | pip install turnstone |
ghcr.io/turnstonelabs/turnstone:stable |
Production-grade. Bugfixes only. |
| Experimental | pip install turnstone --pre |
ghcr.io/turnstonelabs/turnstone:experimental |
New features. May have rough edges. |
See docs/releasing.md for the full release process.
What it does
Turnstone gives LLMs tools — shell, files, search, web, planning — and orchestrates multi-turn conversations where the model investigates, acts, and reports.
- Local-first & private — runs entirely on hardware you control, with no telemetry and no phone-home. Point it at local models (vLLM, llama.cpp) or commercial APIs you hold the keys to — your prompts and data never transit a third party you didn't choose.
- Bring your own models — OpenAI-compatible APIs (vLLM, llama.cpp, NIM), the Anthropic Messages API, and Google Gemini, mixed freely per role
- Interactive sessions — terminal CLI or browser UI with parallel workstreams
- Cluster dashboard — real-time view of every node and workstream, with a rendezvous routing proxy
- Intent validation — an LLM judge (your model) grades every tool call with a risk assessment and evidence before it runs
- MCP support — external tool servers with native deferred loading (Anthropic/OpenAI) or BM25 fallback
- Team controls when you need them — optional RBAC, SSO, tool policies, and audit logs, all stored in your own database
Quickstart
pip install turnstone
# Terminal REPL
turnstone --base-url http://localhost:8000/v1
# Browser UI
turnstone-server --port 8080 --base-url http://localhost:8000/v1
# Cluster dashboard
turnstone-console --port 8090
For PostgreSQL (recommended for production):
export TURNSTONE_DB_BACKEND=postgresql
export TURNSTONE_DB_URL="postgresql+psycopg://user:pass@localhost:5432/turnstone"
turnstone-server --port 8080 --base-url http://localhost:8000/v1
Docker
One-line install — autodetects Ubuntu/Debian, Fedora/RHEL, Arch, and WSL, installs git + Docker if missing, generates secrets, and starts the stack:
curl -fsSL https://raw.githubusercontent.com/turnstonelabs/turnstone/main/run.sh | bash
Or, if you already have Docker, clone the repo and run it yourself:
docker compose up
That builds one image and brings up a full local cluster — PostgreSQL, console,
Caddy, channel gateway, and 10 server nodes — with no .env required (it ships
with insecure dev defaults). Open the dashboard at https://localhost:8443 (Caddy
serves it over TLS with its own local CA — trust it once). Nodes boot without an
LLM; add model backends from the console UI.
For production (released images from ghcr.io, real secrets required), use the
bundled stack: docker compose -f turnstone/deploy/compose.yaml up.
See QUICKSTART.md for the install + troubleshooting walkthrough and docs/docker.md for Docker configuration.
Programmatic (SDK)
from turnstone.sdk import TurnstoneServer
with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
ws = client.create_workstream(name="demo")
result = client.send_and_wait("Analyze the error logs", ws.ws_id, auto_approve=True)
print(result.content)
Tools
Built-in tools for shell, files, search, web, memory, notifications, and autonomous sub-agents — plus external tools via MCP with native deferred loading. See docs/tools.md for the full reference and docs/mcp-registry.md for MCP configuration.
Architecture
Single-node: Client → Server (direct HTTP + SSE). No external dependencies beyond the database.
Multi-node: Client → Console (rendezvous routing proxy) → Server nodes. The console picks the target node for each workstream via rendezvous (HRW) hashing over the live service registry — pure function of (ws_id, live_nodes), no stored bucket state, deterministic across readers. A node join or drop only re-routes the keys that score highest on the affected node.
| Component | Purpose |
|---|---|
turnstone |
Terminal CLI (REPL) |
turnstone-server |
Web UI + REST API + SSE events |
turnstone-console |
Cluster dashboard + routing proxy + admin panel |
turnstone-channel |
Channel gateway (Discord and Slack adapters) |
turnstone-admin |
User/token management CLI |
turnstone-eval |
Headless measurement — scores tool-use against expected actions |
turnstone-optimizer |
Prompt/tool optimizer (UCB self-modify loop over the eval substrate) |
turnstone-doctor |
LLM-backed cluster diagnostics |
Diagrams
UML diagrams in docs/diagrams/:
| Diagram | Description |
|---|---|
| System Context | Components and external dependencies |
| Package Structure | Python modules and dependency graph |
| Core Engine | SessionUI, ChatSession, LLMProvider |
| Conversation Turn | Message lifecycle through the engine |
| Tool Pipeline | Prepare / approve / execute |
| Workstream States | State machine transitions |
| Console Data Flow | Dashboard data collection |
| Deployment | Docker Compose topology |
| Auth | JWT, scopes, login flows |
| Channels | Discord / Slack adapters + routing |
| Judge | Intent validation pipeline |
| OIDC | SSO authorization code flow |
Documentation
| Topic | Link |
|---|---|
| Configuration reference | docs/settings.md |
| API reference | docs/api-reference.md |
| Docker deployment | docs/docker.md |
| Intent validation (judge) | docs/judge.md |
| Governance & RBAC | docs/governance.md |
| OIDC SSO | docs/oidc.md |
| TLS / mTLS | docs/tls.md |
| Channel integrations | docs/channels.md |
| Console dashboard | docs/console.md |
| Eval harness | docs/eval.md |
| Tools reference | docs/tools.md |
| MCP integration | docs/mcp-registry.md |
Requirements
- Python 3.11+
- An OpenAI-compatible API endpoint, Anthropic API key, or Google Gemini API key
- Optional: Discord / Slack channel integrations (
pip install turnstone[discord,slack]) - Git LFS for cloning (diagram PNGs)
Support
Turnstone is free, Apache-2.0, and self-hosted — no paid tier, no telemetry, no upsell. If it saves you time or you'd like to help keep development moving, you can sponsor the project:
❤ Sponsor Turnstone → · one-off via PayPal
Sponsorship is entirely optional and funds maintenance, new features, and infrastructure. Prefer to contribute in other ways? Filing issues, improving docs, and pull requests help just as much.
Community
Questions, ideas, or want to show what you're building? Join us on Discord: discord.gg/Nh3bWMacaq.
License
Apache License 2.0, as of version 1.6.0. Versions 1.5.x and earlier remain under the Business Source License 1.1 they shipped with.