AgentPlane Control

The shared control plane for agent traces and spend.
Chronicle and TokenOps talk HTTP. Only this process owns SQLite. Agents never open the database file.

_{One UI, one SQLite: budgets and policies on the left, a run halted in-path by progress_guard on the right. Chronicle traces live in the next tab.}

AgentPlane Control is the HTTP plane Chronicle and TokenOps share. Sidecars post envelopes and register runs; the plane stores them; Admin, Chronicle, and TokenOps tabs read the same file. No NFS, no two processes fighting over WAL, no "which DB did that agent open."

Why · Architecture · Install · Quick start · Sidecars · Comparison · Design

Why AgentPlane Control

• SQLite lives here. Nowhere else. Chronicle and TokenOps are HTTP clients. They never receive a DB path.
• One pane for both products. Admin keys, Chronicle waterfalls, TokenOps budgets / policies / breaches — same process, same file.
• Ingest is a contract, not a dump. Chronicle writes POST /v1/envelopes:batch (batch_size=1 = flush now) and replays GET /v1/traces/{id}/envelopes. TokenOps registers runs, ledger, and governance over /v1/*.
• Auth when you need it. Empty key table = local anonymous (all scopes, tenant local). Create sidecar keys in Admin, or seed CONTROL_PLANE_API_KEYS.
• pip in, serve, done. No Postgres, no login screen, no separate dashboard server.

Architecture

The plane is one FastAPI process. Agents stay agents.

flowchart LR
    subgraph AGENTS["Agent processes"]
      C["Chronicle sidecar<br/>RemoteStore"]
      T["TokenOps sidecar<br/>HttpStore"]
    end

    subgraph PLANE["Control plane (:8800)"]
      API["HTTP /v1"]
      UI["Admin · Chronicle · TokenOps"]
      DB[("SQLite CONTROL_PLANE_DB")]
      API --> DB
      UI --> API
    end

    C -->|"POST /v1/envelopes:batch"| API
    C -->|"GET /v1/traces/{id}/envelopes"| API
    T -->|"POST /v1/runs · ledger · governance"| API

Design notes: docs/DESIGN.md.

_{Chronicle tab: newest traces first. Click a row for the time-based waterfall.}

Install

pip install agentplane-control-plane

Prerequisites: Python 3.10+. Sidecars are separate packages: agent-chronicle>=0.4.0, agent-tokenops>=0.2.0.

PyPI name is agentplane-control-plane; import is control_plane; CLI is control-plane. See RELEASING.md for releases.

From a clone:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Quick start

control-plane start          # runs in the background; safe to re-run (no-op if already up)
control-plane status         # pid, port, version, /health
control-plane stop

Open http://127.0.0.1:8800/ — Admin, Chronicle, TokenOps. No login.

One managed instance per machine user; start/stop/status track it via a small state file (platformdirs user-state dir) and a PID — stop never touches a process it didn't start. Logs go to a file next to the state (path printed by start), since the process is detached from your terminal.

Prefer the foreground, un-managed form for scripting, containers, or when you want Ctrl-C to stop it:

control-plane serve --port 8800 --db control_plane.db

control-plane ui is a pointer, not a second server: the HTML UI is served with the API.

Docker

For hosting (a shared team plane, a demo environment) rather than a local dev loop:

docker compose up -d      # builds the image, starts on :8800, persists SQLite in a volume
docker compose logs -f
docker compose down       # add -v to also drop the data volume

Or without Compose:

docker build -t agentplane-control-plane .
docker run -d --name control-plane -p 8800:8800 -v control-plane-data:/data agentplane-control-plane

The image's entrypoint is control-plane serve (foreground, PID 1) — not start. Docker/Kubernetes is already the process supervisor here (restart policy, health checks via the built-in HEALTHCHECK hitting /health, log collection from stdout/stderr); start/stop/status are for running the plane directly on a developer's machine, where nothing else is supervising the process. Don't run them inside the container — a background/detached mode would exit PID 1 as soon as it spawned its child, and the container would exit with it.

Set CONTROL_PLANE_API_KEYS before exposing the container beyond localhost — the default (empty) is anonymous, all-scopes access.

Sidecars

Point both libraries at the same origin. Do not set a SQLite path on the agents.

export CONTROL_PLANE_URL=http://127.0.0.1:8800
# TokenOps also honors TOKENOPS_URL; leave TOKENOPS_EMBEDDED unset

Chronicle — flush every envelope to the plane:

import os
import chronicle
from chronicle import RemoteStore

store = RemoteStore(os.environ["CONTROL_PLANE_URL"], batch_size=1)
with chronicle.record("my-run", store=store):
    ...

TokenOps — register runs and share the ledger over HTTP:

from tokenops import ControlPlaneClient, tokenops_run

client = ControlPlaneClient.from_env()  # CONTROL_PLANE_URL or TOKENOPS_URL
with tokenops_run(client=client) as bound:
    ...

Auth off until you create a key. Then:

export CONTROL_PLANE_API_KEYS='chron:local:ingest+read,tops:local:ingest+read,admin:local:read+admin'
export CONTROL_PLANE_API_KEY=chron   # Chronicle / TokenOps sidecar

Or create keys in the Admin tab (secret shown once).

API callers

Every route has one caller class. Agents do not scrape the UI.

How it compares

This is not a gateway, not a SaaS, and not a replacement for Chronicle or TokenOps. It is the shared store + UI those two already assume.

What this does not do: call models, wrap complete, record boundaries, or host a multi-tenant cloud for you. Fail-closed auth is opt-in (create keys). The HTTP contract is still 0.x.

Environment variables

control-plane serve [--host 127.0.0.1] [--port 8800] [--db PATH] [--reload]

Roadmap

The plane is early (0.x). Near-term:

• Harden SQLite under concurrent sidecar writes (busy_timeout, WAL discipline).
• Admin: persist the browser key so a refresh does not 401.
• Keep the HTTP contract stable enough for Chronicle 0.4 and TokenOps 0.2.

Ideas welcome via GitHub issues.

Compatibility

Breaking changes

• 0.2.0 → 0.3.0: run_registrations folded into runs and dropped; PUT /v1/run-records (create_run) removed; PATCH /v1/run-records rejects steps / cost_micros (0.2.x only ignores them); legacy /v1/ledger/halt/* and single-op /v1/ledger/{spent,inflight}/* writes removed. Runs as an automatic PRAGMA user_version v3 migration. Released only after tokenops <next> stops calling create_run.

Full contract: docs/api-contract.md.

Documentation

• API contract — the TokenOps ⇄ control-plane wire spec
• Design — storage, callers, scopes, keys
• Releasing — Trusted Publishing to PyPI
• Changelog
• Chronicle · TokenOps

Contributing

Issues and PRs are welcome.

pip install -e ".[dev]"
ruff check control_plane tests
pytest -v

Contributors

Thanks to everyone who has contributed.

If this is the missing box between your agents and the database, please ⭐ star the repo so more people can find it.