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.

  • 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

Turnstone system architecture

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

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.

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.8.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for eousphoros from gravatar.com eousphoros

Credits

Author: Patrick Buckley

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Provides Extra

all dev discord slack test

Tags

agent ai chat llm openai tools

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

turnstone-1.8.0.tar.gz (8.2 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

turnstone-1.8.0-py3-none-any.whl (5.1 MB view details)

Uploaded Python 3

File details

Details for the file turnstone-1.8.0.tar.gz.

File metadata

  • Download URL: turnstone-1.8.0.tar.gz
  • Upload date:
  • Size: 8.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for turnstone-1.8.0.tar.gz
Algorithm Hash digest
SHA256 293b44214b0b90170e07d17c11db53212e67d056830e4842b72884076e96b356
MD5 eaff72d2482bf457c36d45034b6add72
BLAKE2b-256 dfbcf07fe421b8ccdf2978e661c9683977c729a6307d543683354745adc0cc08

See more details on using hashes here.

Provenance

The following attestation bundles were made for turnstone-1.8.0.tar.gz:

Publisher: publish.yml on turnstonelabs/turnstone

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file turnstone-1.8.0-py3-none-any.whl.

File metadata

  • Download URL: turnstone-1.8.0-py3-none-any.whl
  • Upload date:
  • Size: 5.1 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for turnstone-1.8.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a7cf3bed3b0f790a3b5591ff589e5779cdfd8856dc5794ea4271fb0cb2b46840
MD5 6bace9c03dde45c8ebaace8f1ac25d3a
BLAKE2b-256 b2d40cd139c03fcc1f8cf911673e0ae7a5d2de0a30ac9b277f866e19448f01ad

See more details on using hashes here.

Provenance

The following attestation bundles were made for turnstone-1.8.0-py3-none-any.whl:

Publisher: publish.yml on turnstonelabs/turnstone

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.8.1

2 files

This release

1.8.0 This release

2 files

Pre-release

1.8.0a6

2 files

Pre-release

1.8.0a5

2 files

Pre-release

1.8.0a3

2 files

Pre-release

1.8.0a2

2 files

Pre-release

1.8.0a1

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

Pre-release

1.7.0rc1

2 files

Pre-release

1.7.0a6

2 files

Pre-release

1.7.0a5

2 files

Pre-release

1.7.0a4

2 files

Pre-release

1.7.0a3

2 files

Pre-release

1.7.0a2

2 files

Pre-release

1.7.0a1

2 files

1.6.9

2 files

1.6.8

2 files

1.6.7

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

Pre-release

1.6.0rc2

2 files

Pre-release

1.6.0rc1

2 files

Pre-release

1.6.0a12

2 files

Pre-release

1.6.0a11

2 files

Pre-release

1.6.0a10

2 files

Pre-release

1.6.0a9

2 files

Pre-release

1.6.0a8

2 files

Pre-release

1.6.0a7

2 files

Pre-release

1.6.0a6

2 files

Pre-release

1.6.0a5

2 files

Pre-release

1.6.0a4

2 files

Pre-release

1.6.0a3

2 files

Pre-release

1.6.0a2

2 files

Pre-release

1.6.0a1

2 files

1.5.18

2 files

1.5.17

2 files

1.5.16

2 files

1.5.15

2 files

1.5.14

2 files

1.5.13

2 files

1.5.12

2 files

1.5.11

2 files

1.5.10

2 files

1.5.9

2 files

1.5.8

2 files

1.5.7

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

Pre-release

1.5.0a5

2 files

Pre-release

1.5.0a4

2 files

Pre-release

1.5.0a3

2 files

Pre-release

1.5.0a2

2 files

Pre-release

1.5.0a1

2 files

1.4.0

2 files

Pre-release

1.4.0a4

2 files

Pre-release

1.4.0a3

2 files

Pre-release

1.4.0a2

2 files

Pre-release

1.4.0a1

2 files

1.3.1

2 files

1.3.0

2 files

Pre-release

1.3.0a3

2 files

Pre-release

1.3.0a2

2 files

Pre-release

1.3.0a1

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

Pre-release

1.2.0a5

2 files

Pre-release

1.2.0a4

2 files

Pre-release

1.2.0a3

2 files

Pre-release

1.2.0a1

2 files

1.1.1

2 files

1.1.0

2 files

Pre-release

1.1.0a3

2 files

Pre-release

1.1.0a2

2 files

Pre-release

1.1.0a1

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.9.10

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.9

2 files

0.8.8

2 files

0.8.6

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.0

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.5

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page