UNITARES

Coordination and self-state telemetry for long-lived AI-agent fleets.

An agent that runs for weeks is not the same kind of object as a chat turn. It accumulates claims, drifts, restarts, and gets replaced by a fresh process wearing the same display name. Every individual tool call can be permitted while the process as a whole comes apart.

Evals ask whether a model is good enough for a task. Guardrails ask whether one action is allowed. Traces record what a single run did. None of them answer the question an operator running a fleet actually has:

Is this the same agent as yesterday, and is it working the way it usually works?

At each checkpoint UNITARES binds the write to a process identity, records what the agent claims alongside whatever evidence exists, updates a longitudinal state estimate, and returns a policy action with a named reason. The whole chain stays replayable, and two live processes can contend for the same governed surface without silently colliding.

Self-hosted and single-operator by design. MCP is the primary agent-facing interface; REST, the public SDK, host adapters, and the dashboard expose the same core. Plain-language definition: What UNITARES is.

Status: v2.20.0. Running continuously since November 2025. Evidence and limits gives every claim its evidence class, including the open ones.

Quickstart

git clone --branch v2.20.0 --depth 1 https://github.com/cirwel/unitares.git
cd unitares
docker compose up -d --wait
make coordination-demo

This release-tagged Docker Compose flow is the supported install path for a local, single-operator deployment. It brings up PostgreSQL/AGE/pgvector, Redis, the lease plane, and the server on loopback without manual database initialization. After cloning, the one-command install/start is docker compose up -d --wait.

make coordination-demo gives the first observable result: two participants onboard through governance; governance exchanges their continuity credentials for single-use, request-bound Ed25519 attestations; A's attestation is refused when it claims B's UUID; a captured attestation is refused on replay; and one governed maintenance:/ surface moves through an identity-checked atomic handoff before release. The printed receipt also names the boundary: clients must participate in the lease plane, and this local demo does not exercise a second operator or establish improved outcomes.

To exercise longitudinal state next, run make demo. It onboards a fresh process and sends six check-ins over the real API, printing the response shape, decision reason, state detail, and warmup position.

The dashboard is at http://localhost:8767/dashboard; MCP clients connect to http://localhost:8767/mcp/; the lease plane listens on http://127.0.0.1:8788 with bearer auth.

Evaluating rather than installing? Start with Evidence and limits and the Reviewer Guide. For deployment and integration, use the user manual.

Related MCP server: hejdar-mcp

The checkpoint loop

Everything else in this repository is built on one small, explicit loop.

The returned policy action, reason, next step, and enforcement record are the stable integration boundary.

Four optional surfaces build on that record:

Identity binding is what makes stored findings, reviews, and leases attributable to a process rather than to a display label. The Docker quickstart enforces this for maintenance:/ leases; other kinds remain staged until all of their producers carry proofs. Governance keeps the continuity credential and private signing key; the lease plane verifies a short-lived token bound to a deployment-specific audience plus the exact method, path, and request-body hash, then consumes its nonce once. This version accepts one explicitly trusted issuer. Multi-issuer federation remains blocked until lease principals persist both issuer and subject; active leases must be drained before changing issuer. legacy, hybrid, and attestation proof modes support staged upgrades. Operators inspect lifecycle, state, evidence, and policy history through MCP/HTTP APIs and the self-hosted dashboard. The public unitares-sdk handles connection, identity, check-ins, heartbeats, and knowledge participation for resident agents.

Where it fits

UNITARES runs alongside evals, guardrails, and sandboxes. It replaces none of them.

It is built for long-lived coding, research, operations, monitoring, and multi-agent processes that can instrument a check-in loop, and is usually not worth the overhead for short-lived chat turns.

UNITARES is a state instrument, not an outcome oracle. It does not decide whether an output is correct or ethical, and it cannot detect deliberate concealment without independent evidence. The scope and threat model draws that boundary precisely.

It governs the agent's loop from outside rather than owning it, so Claude Code, Codex, Hermes, custom runtimes, and resident agents stay different userlands while sharing one accountable record and policy surface.

The lowercase residents under agents/ are reference clients and operational examples, not the Resident product and not a framework to subclass.

Integrate an MCP client

start_session and sync_state are tools exposed by the connected UNITARES server. A fresh process creates its own identity, then includes the returned session binding on later writes:

session = start_session(force_new=True)

result = sync_state(
    response_text=output,
    complexity=0.6,
    confidence=0.8,
    client_session_id=session["client_session_id"],
)

if result.get("success") is False:  # refused write, e.g. the agent is paused
    return_to_operator(result.get("recovery"))
elif result.get("state_summary", {}).get("action") == "pause":
    return_to_operator(result.get("next_action"))  # application-defined boundary

success=False means the governed write was refused. A pause returned on an accepted response is the host's to honor, at surfaces UNITARES does not own.

For a durable resident, preserve its identity anchor rather than minting a new identity on every run; the SDK lifecycle example handles that continuity. Pair self-reported confidence with verifiable evidence wherever possible:

See the advisory consultation facade proposal for the routing, privacy, and authority contract behind consult.

When recording an outcome for a specific check-in, pass the prediction_id from that check-in's response so the outcome grades that claim rather than an unrelated earlier one.

list_tools() enumerates the complete live surface and describe_tool(tool_name=...) explains any one tool. MCP, REST, the SDK, and host adapters all reach the same server.

How the runtime loop works

Clients can treat the policy action, reason, and next step as the stable contract. Operators can optionally inspect four EISV coordinates covering work progress, evidence alignment, behavioral drift, and their balance. EISV is self-state estimation: a read of how the process is working, drawn from auditable, published heuristics. The computation reference documents formulas, warmup, thresholds, and source code; the interpretation contract records which readings are supported and which are not.

Local control and future federation

Identity, telemetry, evidence, and policy history stay on infrastructure you control, with no outbound dependency on a vendor service.

The architecture exposes several of the seams a later federation experiment would need: process-bound identity, evidence provenance, a versioned telemetry envelope, and policy decisions with named reasons.

The blocker is named, not unknown. Resolution attestations are HMAC keyed on each agent's api_key. That is symmetric: a verifier needs the signing key, and holding it would also let them forge a signature. Sound for its deployed purpose of one operator attesting inside their own trust boundary, and explicitly not non-repudiation. Asymmetric or DPoP-style keys were considered and shelved on 2026-04-19, so until that is revisited a record from this system cannot be verified by an operator who does not already trust its issuer, which is the whole problem a federation exchange has to solve. Whether the remaining records suffice to exchange cross-operator attestations without centralizing raw telemetry is open on the multi-principal trust track in the roadmap.

What is built

One operator, since 2025-11-20. The counts below are structural facts about this repository and its companions, not a claim that any of it outperforms an alternative. They answer one question an evaluator reasonably asks first: is this a prototype or a system?

Evidence and limits

Every claim below carries an evidence class saying what it licenses. An evidence class says what a result supports; it is not a positive or negative judgement about the project.

A registered operational FAIL can close a scheduled line of work without scientifically refuting the underlying capability. A claim earns REFUTED only when the target, counterfactual, independent unit, support and power, decision rule, and read protocol all support that conclusion. The inference-status contract defines those boundaries.

At the 2026-08-11 frozen snapshot, the maintainer deployment provided operational evidence that the system runs at length under real load:

The maintainer deployment is single-operator and co-development dogfood: most agents governed by the system are also building the system. Read DEPLOYMENT_DATA_CAVEAT.md before citing a fleet number.

Current claim status

The outcome read carries a protocol qualification. After the frozen cutoff, recurring automation exposed live discrimination output: the ablation watchdog completed 42 of 51 executions and the dogfood guard completed 43 of 52. Those jobs are paused. The fixed 2026-12-01 gate remains an operational decision rule, but it is not the only post-registration read and cannot be described as clean single-read blinding; its report must disclose the interim access and read-specific power.

The instrument-frame validation the system does claim, meaning reliability, faithfulness under intervention, and calibration, is scoped and partly built; the roadmap tracks it. The companion DOI identifies a public preprint, not peer-reviewed validation.

Architecture, setup, and documentation

Python 3.12+ · PostgreSQL + AGE + pgvector · Redis · optional Elixir/OTP coordination. Redis holds session and identity state, and the Docker quickstart brings it up. The server starts without it in a degraded local-only mode, which is not the supported path.

The complete documentation map is docs/README.md. Optional analogies and philosophical readings are isolated under docs/essays/; they are not specifications or evidence.

Project operation is explicit: see the roadmap, compatibility and naming map, governance, contributing guide, security policy, support policy, and release process.

Ecosystem repositories

These are adjacent integrations, testbeds, and research projects; the core quickstart does not require them.

Citation and license

Kenny Wang (ORCID 0009-0006-7544-2374), CIRWEL Systems. See CITATION.cff for the versioned citation. The DOI below identifies a public preprint, not peer-reviewed validation; see Evidence and limits.

@misc{wang2026unitares,
  author = {Wang, Kenny},
  title  = {{UNITARES}: Information-Theoretic Governance of Heterogeneous Agent Fleets},
  year   = {2026},
  doi    = {10.5281/zenodo.19647159}
}

Apache License 2.0. See LICENSE and NOTICE.