Gents

An agent runtime where the database is the control plane.

Gents runs LLM agents on top of DefraDB: every piece of state — configuration, requests, responses, sessions, tool calls, schedules — is a replicated, access-controlled document. Agents get verifiable DID-based identity, document-level permissions, and P2P event propagation for free, because the database provides them.

Get running

Everything local, on a Mac, in a few minutes:

brew install llama.cpp
llama-server -hf google/gemma-4-12B-it-qat-q4_0-gguf   # local inference on :8080

# Install the Codex CLI separately and make sure `codex` is on PATH.
# `gents chat` remains the dependency-free fallback UI.

gh release download --repo source-inc/gents -p 'gents-aarch64-apple-darwin.tar.gz'
tar -xzf gents-aarch64-apple-darwin.tar.gz
sudo install gents-aarch64-apple-darwin/gents /usr/local/bin/gents

gents init      # provision a safe read-only agent under ~/.gents
gents server    # start the runtime (embedded DefraDB + GraphQL + P2P)
gents codex     # launch Codex against the Gents app-server shim

The getting-started guide walks every step and the paths off it: letting the agent change things (init --write / --yolo, and what each preset guarantees), pointing init at other OpenAI-compatible backends, verifying the signed binary, building from source, and the fallback chat REPL. Desktop app, fleet bring-up, and P2P pairing: docs/operations.md. Operators performing the breaking product cutover should use the single Gents cutover runbook. The plan for packaging the desktop chat, fleet, and Tauri bridge surfaces for downstream apps (#877) is specified in docs/reusable-desktop-packages.md.

For the interactive fleet demo, run gents demo — it ships in the binary, no checkout, make, or mock required. It boots a single curated agent (read-only tools + demo skills) on a backend you pick on first run, then drops into a demo> shell: chat with the agent, pair a 2nd node (a Worker), delegate a cross-node subagent that runs on the worker over P2P (the result replicates back), desktop to open the same fleet through the native Fleet Dashboard UI, and reconfigure to switch backends. New chat turns use the configured model backend, reachable on both nodes. Keep the local llama-server above running, or launch with a hosted preset and model, e.g. OPENAI_API_KEY=... gents demo --backend-preset openai --model gpt-5.4-mini. Add --desktop to launch the native app as soon as the runtime is ready.

Why this exists

Agent frameworks bolt persistence, identity, and coordination onto a loop. Gents inverts that: the loop is thin and formally specified, and the hard properties come from the substrate.

• The data store is the control plane. Configure an agent by writing documents; trigger work by writing documents; debug by reading them. The runtime watches request documents and writes responses back. Multi-agent coordination is document replication, not RPC.
• Identity is cryptographic and layered. A principal (DID) is the permission and audit boundary. Behaviors — prompt, tools, model — are reusable interfaces on a principal. Deployments place principals on hosts. Least privilege falls out of the model.
• The core is proven. The request, process, persistence, tool-call, and subagent lifecycles — and what the runtime feeds the model — are specified in Lean 4 with zero sorrys, fenced by conformance tests, and only then implemented. See the proofs.

Architecture

            documents in ────────────► documents out
                 │                            ▲
   ┌─────────────▼────────────────────────────┴──────────────┐
   │  Gents runtime (the core)                              │
   │  watcher → request lifecycle → owned completion loop    │
   │  → tool surface (files/bash/MCP/subagents/skills)       │
   │  → persistence hooks → live response streaming          │
   ├─────────────────────────────────────────────────────────┤
   │  embedded DefraDB: identity (DID) · ACL · P2P           │
   └─────────────────────────────────────────────────────────┘
        ▲                ▲                  ▲
     CLI (operate)   desktop (observe)   other peers (replicate)

• Runtime (crates/gents) — the agent loop, lifecycles, tool execution, triggers/schedules, compaction, recovery. The core; everything else supports it.
• Protocol (crates/gents-protocol) — schemas, the persisted message vocabulary, and the turn-observation protocol shared by every peer.
• CLI (crates/gents-cli) — init/serve/chat, plus declarative config apply/diff: agent manifests in, documents out.
• Desktop (apps/gents-desktop, crates/gents-desktop*) — an observer UI over the same documents, paired via P2P.
• Proofs (crates/gents/proofs) — the Lean models the runtime conforms to.

Subagents are requests: a parent's tool call spawns a child request — possibly on another deployment — and the child's terminal state projects back onto the parent's transcript. Automation is the same shape: Tasks, Schedules, and EventTriggers materialize requests with lineage stamped on every one.

Development

Building from source needs a few system dependencies (Rust, a C/C++ toolchain, protoc, libclang, and OpenSSL headers). DefraDB dependencies are public and use pinned HTTPS revisions. Build, test, and toolchain setup live in DEVELOPMENT.md.

The development flow is foundation-first: Lean model → conformance tests → implementation. CLAUDE.md is the working brief; the proofs README maps the formal coverage.

Status

Pre-1.0 and under active development. Extracted from a larger system (Amygdala) and intentionally narrow: the runtime and its formal specification.

License

Licensed under the Apache License, Version 2.0.