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
Что это?Turnstone — self-hosted, local-first фреймворк оркестрации, дающий LLM настоящие инструменты — shell, файлы, поиск, веб, планирование — и ведущий многоходовые диалоги агентов на вашем собственном кластере.
Это CLI-инструмент, SDK или полноценный серверный стек?Сразу всё: терминальный CLI (turnstone), программный Python SDK и стек сервер/консоль с веб-панелью и REST/SSE API, который разворачивается через Docker.
Как его запустить?Возьмите однострочный Docker-установщик: он сам определяет вашу ОС, ставит git и Docker, если их нет, генерирует секреты и поднимает PostgreSQL, консоль, Caddy, шлюз каналов и 10 серверных узлов — .env не требуется.
Какие бэкенды моделей и провайдеры LLM можно использовать?Поддерживаются OpenAI-совместимые API (vLLM, llama.cpp, NIM), Anthropic Messages API и Google Gemini, свободно смешиваемые по ролям; для нативных установок нужен Python 3.13+.
Есть ли подводные камни обновления или установки, о которых стоит знать?Turnstone 1.9 требует Python 3.13+, отказавшись от поддержки 3.11/3.12 из серии 1.8, так что обновление нативной установки означает пересоздание virtualenv; Docker-установки вместо этого несут с собой нужную среду Python.
Кто управляет доступом, когда одним кластером пользуются несколько человек?Команды могут включить опциональные RBAC, SSO (OIDC), политики инструментов и журналы аудита, причём всё это хранится в вашей собственной базе, а не у стороннего провайдера.
Можно запустить на Windows через WSL или только на нативном Linux?Установщик прямо поддерживает Ubuntu/Debian, Fedora/RHEL, Arch и WSL, так что это работает на нативном Linux, на macOS через Docker и на Windows через WSL.
Покидают ли мои данные или код мою машину?Нет — Turnstone спроектирован работать целиком на железе под вашим контролем, без телеметрии и «звонков домой», используете ли вы локальные модели или собственные API-ключи.
Что такое «судья валидации намерений» (intent validation judge)?Это LLM (ваша собственная модель), которая до исполнения оценивает каждый вызов инструмента, выставляя оценку риска с подтверждающими доводами, — своего рода предохранительный шлюз для действий агента.
Как работает маршрутизация между узлами?В многоузловом режиме прокси консоли выбирает целевой серверный узел для каждого рабочего потока при помощи rendezvous (HRW) хеширования по живому реестру сервисов, поэтому маршрутизация детерминирована и при входе или уходе узла перенаправляет только затронутые ключи.
Можно ли подключить Turnstone к Discord или Slack?Да, есть шлюз turnstone-channel с адаптерами для Discord и Slack, ставится через опциональный extra pip install turnstone[discord,slack].
Как он поддерживает внешние инструменты помимо встроенных?Через серверы MCP (Model Context Protocol), с нативной отложенной загрузкой для моделей Anthropic/OpenAI либо резервным поиском BM25 для обнаружения инструментов.
What are similar projects?hive, evenfire, brigade, ruflo, Agentlas-OS, cayu, casdoor, trueforge
Which topics is it in?bm25, sse, wsl, llamacpp, audit-log, oidc, jwt, sso, rbac, oauth2, slack, discord
Creator
turnstonelabs
Size
38.6 MB
Stars
1.6K
Updated
CommitOct 17Releasev1.8.7Oct 15
Age
7mo
Commits · 90 Days