turnstone README

The project's README from github.com/turnstonelabs/turnstone. As one markdown file: README.md.

Turnstone

CI PyPI Python License Discord Sponsor

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.

Turnstone coordinator — parallel tool batches with judge-graded approval and child workstream tracking

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 whole controlled loop: π lowers state to context, M_W proposes a readout, γ authorizes it, Q_E acts on the world, ρ verifies and folds back 

ℋ :  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.

Repository branches

Beginning with 1.8.0, stable releases and next-release development use distinct branches:

Branch Role Pull requests
main Current stable release and install source Fixes that should ship on the current stable line
dev Next release integration and GitHub default Features, refactors, and development-only fixes
stable/X.Y Maintained prior release line Fixes for that supported older minor

GitHub defaults to dev, so new pull requests and ordinary source clones start on the development line. Stable-source install paths explicitly select main. There is no independently writable stable/X.Y mirror for the minor currently on main. Before main advances to the next stable minor, its current tip is preserved as that minor's maintenance branch. Maintainers then merge fixes forward (stable/X.Y → main → dev) so the branches retain shared ancestry without recurring cherry-picks.

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.

The browser's Default / Compact control saves your transcript preference in that browser. Compact hides reasoning text and folds completed successful tool details. Both views show a Reasoning indicator with elapsed seconds while the model prepares its answer. The clock starts when the browser observes that phase and continues as reasoning tokens arrive; reconnecting to an existing phase starts a new clock if its start was not observed. Completed history has no estimated reasoning duration.

Turnstone system architecture

Quickstart

Use Python 3.13 or 3.14; the commands below use 3.13.

python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install turnstone

# Terminal REPL
turnstone --base-url http://localhost:8000/v1

# Browser UI — define models in the console Models tab, or in
# ~/.config/turnstone/config.toml:
#   [models.local]
#   base_url = "http://localhost:8000/v1"
#   model = "qwen3-32b"
turnstone-server --port 8080

# 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

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 stable source and run it yourself:

git clone --branch main https://github.com/turnstonelabs/turnstone
cd turnstone
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.

For optional SSO, per-user MCP OAuth, or model gateway authentication, the installer and both stacks support one shared authentication config. The default local-login setup needs no additional configuration.

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, docs/mcp-registry.md for MCP configuration, and MCP authentication for auth choices and remote Docker/GitHub OAuth setup.

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
OAuth Storage Shared token store, captured credentials, and MCP state

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
MCP authentication / OAuth docs/mcp-oauth.md

Requirements

Turnstone 1.9 requires Python 3.13 or newer; 1.8 is the last series supporting Python 3.11 and 3.12. To upgrade a native installation, recreate its virtual environment with Python 3.13 or 3.14 and reinstall Turnstone. Docker installations include the required Python runtime.

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.

turnstone (turnstonelabs/turnstone)

Searching Database…

1.6K ·GitHub
Turnstone
What is this?Turnstone is a self-hosted, local-first orchestration framework that gives LLMs real tools — shell, files, search, web, planning — and runs multi-turn agent conversations across your own cluster.
Is it a CLI tool, an SDK, or a full server stack?It is all three: a terminal CLI (turnstone), a programmatic Python SDK, and a server/console stack with a web dashboard and REST/SSE API that you can deploy via Docker.
How do I get it running?Use the one-line Docker installer, which autodetects your OS, installs git and Docker if missing, generates secrets, and spins up PostgreSQL, the console, Caddy, a channel gateway, and 10 server nodes with no .env required.
Which model backends and LLM providers can I use?It supports OpenAI-compatible APIs (vLLM, llama.cpp, NIM), the Anthropic Messages API, and Google Gemini, mixed freely per role, and needs Python 3.13+ for native installs.
Any upgrade or install pitfalls I should know about?Turnstone 1.9 requires Python 3.13+, dropping support for 3.11/3.12 from the 1.8 series, so upgrading a native install means recreating the virtualenv; Docker installs bundle the required Python runtime instead.
Who manages access when multiple people use the same cluster?Teams can enable optional RBAC, SSO (OIDC), tool policies, and audit logs, all stored in your own database rather than a third party's.
Can I run this on Windows via WSL, or only native Linux?The installer explicitly supports Ubuntu/Debian, Fedora/RHEL, Arch, and WSL, so it works on native Linux, macOS via Docker, and Windows through WSL.
Does my data or code ever leave my machine?No — Turnstone is designed to run entirely on hardware you control with no telemetry or phone-home, whether you use local models or your own API keys.
What is an 'intent validation judge'?It is an LLM (your own model) that grades every tool call with a risk assessment and supporting evidence before it is allowed to run, acting as a safety gate on agent actions.
How does multi-node routing work?In multi-node mode, a console proxy picks the target server node for each workstream using rendezvous (HRW) hashing over the live service registry, so routing is deterministic and only re-routes affected keys when a node joins or drops.
Can I connect Turnstone to Discord or Slack?Yes, there is a turnstone-channel gateway with adapters for Discord and Slack, installable via the optional pip install turnstone[discord,slack] extra.
How does it support external tools beyond the built-ins?Through MCP (Model Context Protocol) servers, with native deferred loading for Anthropic/OpenAI models or a BM25 fallback search for tool discovery.
What are similar projects?hive, evenfire, brigade, ruflo, Agentlas-OS, cayu, casdoor, trueforge
Which topics is it in?bm25, wsl, sse, llamacpp, audit-log, oidc, jwt, sso, rbac, oauth2, slack, discord
Creator
turnstonelabs
Size
37.5 MB
Stars
1.6K
Updated
CommitOct 15Releasev1.8.7Oct 15
Age
7mo
Commits · 90 Days