A governed agent mesh that decomposes one AI agent into fourteen specialized roles so no single component can both decide and act, with structurally enforced safety, bounded self-correcting loops, measured self-improvement, repeatable task memory, and conditional self-healing.
An open-source project by Coeus Institute, free and open under AGPL-3.0.
Important
The core invariant. Anything that can decide cannot act. Anything that can act cannot act unsupervised.
- What this is
- Background
- Installable runtime and buildable spec
- Architecture
- Dataflow
- Looping
- Self-improvement
- The fourteen agents
- Directory structure
- Model binding
- How "no gaps" is guaranteed
- Documentation that cannot drift
- Extending it
- Where to look
- License & commercial use
Most agent frameworks try to make a single model trustworthy enough to be handed power, then bolt on a content filter. Polos starts somewhere else: assume no single component is fully trustworthy, and make the system's properties hold structurally, as a consequence of how the agents are wired, not of any one model behaving. Resisting prompt injection falls out of that wiring, but it is the floor, not the pitch.
The mesh is built around five capabilities that have to hold at the same time for autonomy to be safe:
| Capability | How | |
|---|---|---|
| π‘οΈ | Structural safety | Deciders hold no tools; one role acts, only on scoped, time-boxed, monitored grants; tool-less guardians can reject / rework / quarantine / halt but never act. Safety is a property of the topology. |
| π | Safe looping | Run a task as a bounded, externally verified loop (the loop-engineering / Ralph pattern), with budgets, a Verifier-checked stop condition, and fresh-context-from-ledger, so it can't infinite-loop, drift, or explode in cost. β docs/LOOPING.md |
| π | Measured self-improvement | Get better over time by accumulating evidence-tested, reversible lessons and playbooks, proposed by one agent, measured by a different one, ratified before commit, so the mesh never expands its own authority. β docs/SELF-IMPROVEMENT.md |
| π§ | Repeatable task memory | Record a redacted environment profile and ratified playbooks so shorthand requests like "push to GitHub," "deploy to Vercel," or "migrate Supabase" expand into safe preflight β action β verification workflows. β docs/PLAYBOOKS.md |
| π©Ί | Conditional self-healing | Run a Nurse checkup only when a user asks, Security raises integrity concerns, or repeated audit signals cross threshold/cooldown; Nurse diagnoses and prescribes repairs, but normal actors perform them under gates. β docs/NURSE.md |
The same discipline that contains an untrusted model is exactly what makes looping and self-improvement safe to switch on. That combination, not prompt-injection defense alone, is the point.
Claude Code, Codex CLI, OpenCode, and Agent Zero are strong because a capable model can directly read, write, and run things. Polos keeps that capability but routes it through a structurally governed authority chain: the model that decides what to do never holds the tools; the single role that does hold tools acts only on a scoped, time-boxed grant; and tool-less guardians can reject, rework, quarantine, or halt at any point. You get real agentic action and a system where no single mistaken or manipulated model can both choose a harmful action and carry it out. That is the structural advantage the rest of this README makes concrete.
- The spec β authoritative. A runtime-neutral governed-agent mesh: the immutable constitution, 14 role cards, the one message envelope, the complete flow graph, the state machine, and model bindings β plus a validator that mechanically proves the wiring has no gaps. An agent reads this and assembles the mesh in your environment.
- The reference runtime β
polos/, v0.3. An installable Python package andpolosCLI that makes the kernel runnable locally: durable task contracts, a fail-closed policy engine, JIT grants, a governed tool gateway, hash-chained audit, verifier-gated loops, a model router, and host adapter interfaces. It is one host mapping and is never more authoritative than the spec.
Polos was designed over roughly two years by Coeus Institute, originally as an internal harness for our own development and operational work. It began as a practical answer to a practical problem: we wanted to run capable AI agents against real code and real infrastructure without accepting the risk that a single wrong or manipulated model could take a damaging action. Instead of trusting one model and bolting on a filter, we built the decide/act separation into the structure of the system and hardened it in daily use.
The harness grew with the field. As the research literature and the practitioner community produced novel methods, we studied them, tested what held up against our own workloads, and folded the durable ideas into the architecture. Experiments matured into first-class subsystems: bounded, externally verified looping; measured, authority-preserving self-improvement; repeatable task memory; and conditional self-healing. Each was adopted only once it could be expressed as part of the connection graph and checked mechanically, so a new capability never came at the cost of the core invariant. The result combines some of the strongest results from the papers and open projects it cites under one structural safety model, rather than bolting them together as independent features.
Polos is a powerful harness, and it is tailored for organizations that work through AI-leveraged IDEs and coding agents such as Claude Code, Cursor, VS Code, and GitHub Copilot. It is designed to self-assemble: an agent reads the specification and constructs the mesh around an existing codebase on whatever stack the organization already uses, then proves the result is complete with the validator before going live.
Coeus Institute is glad to release Polos under the AGPL-3.0 license. We believe the agentic industry moves forward fastest when the most cutting-edge techniques are openly available rather than held privately. Sharing the harness we rely on internally is a direct expression of that goal: to give the public access to a rigorously safe, continuously improving foundation for governed autonomy, and to invite the wider community to scrutinize, measure, and build on it in the open.
Polos is still a portable governed-agent mesh specification first: the constitution, role cards, contracts, flow graph, state machine, model bindings, and validator remain authoritative. It now also ships an initial Python runtime layer, Polos Core Runtime v0.3, so the safety kernel can be used as a local CLI harness with durable task contracts, fail-closed policy, JIT grants, audit logging, verification evidence, and bounded loop scaffolding.
Install the local runtime from a clone:
pip install -e ".[dev]" # install the `polos` CLI (PyYAML + jsonschema)
polos version # 0.3.0
polos validate # runs tools/validate_mesh.py β must print PASS
polos init # scaffold .agent/ runtime state + a redacted environment profile
polos plan "test task" # write a durable task contract under .agent/tasks/<id>/
polos run --dry-run # run required checks, write EVIDENCE.md; no tools or model calls
polos audit # list task records + verify the hash-chained tool-call logNo API keys are needed for validate, init, plan, or run --dry-run, so you can exercise the
governed-authority chain locally before any model or provider is wired in.
There are still two ways in: run the packaged local runtime directly, or hand the build protocol to your agent so it maps the mesh onto your host environment.
This is the primary path. Polos is written to be built by an agent, into the environment that agent already works in. The repo is laid out so it can self-assemble the mesh with no manual wiring:
AGENTS.mdβ the entry point and directory map (what every folder owns).BUILD.mdβ the procedure: eleven ordered steps, each naming the exact file to read and what to wire next, so even smaller models can follow it literally.adapters/β how to map the runtime-neutral spec onto your host (VS Code / Copilot, Claude Code, Codex, LangGraph, or a generic loop).tools/validate_mesh.pyβ the proof: it must printPASSbefore the mesh goes live.
If Polos is already open in your AI coding tool, the shortest instruction works: βRead AGENTS.md, then follow BUILD.md to construct the mesh in this environment.β Starting from a different project? Paste the prompt below and the agent will fetch Polos first, then build it around your code:
You are an agent. Build the Polos governed-agent mesh into THIS environment, following its own spec.
1. Get the spec. If Polos is not already in my workspace, clone https://github.com/CoeusInstitute/Polos
(or read it in place). Open AGENTS.md FIRST β it is the entry point and directory map.
2. Detect my host and pick the matching note in adapters/ (use adapters/generic.md if none fits).
The host MUST be able to deny tools to deciders and oversight. If it cannot, STOP and tell me.
3. Load constitution/core.md and hold it read-only β it is immutable for the build.
4. Resolve models in models.yaml: one line per role. Keep oversight (Monitor, QC, Security) and the
Evaluator on a DIFFERENT model lineage than the deciders and workers (anti-correlated failure).
5. Instantiate all 14 roles from roles/*.agent.md with ONLY the capabilities each card declares.
Workers get NO standing credentials β the Taskmaster mints scoped, time-boxed grants per assignment.
6. Wire the flow graph (contracts/flow.graph.yaml). Every message must validate against
contracts/envelope.schema.json, and senders NEVER choose their own gates β the graph assigns them.
7. Wire the state machine (contracts/state-machine.md). Default on uncertain or unavailable = BLOCK.
8. Stand up oversight: the audit log, Security's independent verdict feed, HALT/quarantine to every
plane, and the conditional Nurse triage (read-only, threshold + cooldown gated).
9. Run the DOX Archivist pass so every directory's AGENTS.md is current and reachable from the root.
10. Self-test: send one benign request (expect a response) and one out-of-scope request (expect a gate
to block it); confirm the audit log captured every hop.
11. Run `python tools/validate_mesh.py` and show me the output. It MUST print PASS.
Hard rules β never weaken these while building:
- Deciders (Alpha, Router, Taskmaster, Loop Controller) and oversight (Monitor, QC, Security, Evaluator)
hold NO tools. The Execution Worker is the only actor, and only on a scoped, time-boxed grant.
- Fail closed. Loops need an externally verifiable stop condition checked by the Verifier. Self-improvement
may propose measured, reversible lessons but can NEVER grant authority or relax a gate.
- Do not weaken the constitution, contracts, flow graph, or validator. Do not go live on a failing invariant.
Already inside an existing harness? Use the same protocol but tell the agent to merge, not replace: preserve your current specs and tooling and add Polos's governance on top, then run the validator.
That is enough for a capable agent: every step names the exact file to read and what to wire next, and the validator mechanically proves the result is complete.
- Clone the spec.
git clone https://github.com/CoeusInstitute/Polos.git cd Polos - Verify it's intact. The validator mechanically proves the spec has no gaps before you build on it.
pip install -r tools/requirements.txt python tools/validate_mesh.py # expect: PASS - every enforced completeness invariant holds. - Bind your models. Edit
models.yaml, one line per role. Keep oversight (Monitor/QC/Security) and the Evaluator on a different model lineage than the workers; that anti-correlation is what stops a jailbreak of one model from fooling its guardian. - Pick your adapter. Choose the note in
adapters/that matches your stack:vscode-copilot.md,langgraph.md, orgeneric.md. It explains how to deny tools to deciders and oversight in your runtime (the one rule a host must enforce). - Install and test the runtime.
pip install -e ".[dev]" polos validate python -m pytest - Build it for your host. Follow
BUILD.md: readAGENTS.mdfor the map, then wire the roles, the flow graph, and the gates as it directs. Re-runpython tools/validate_mesh.pywhen you're done and confirm it still printsPASS.
Three planes do the work: intent, orchestration, execution. One plane guards it: oversight. One plane adapts it: adaptation.
flowchart TB
H([Human Principal])
subgraph INTENT["Intent Β· no tools"]
A[Alpha]
end
subgraph ORCH["Orchestration Β· deciders, no tools"]
R[Router]
T[Taskmaster<br/>mints JIT credentials]
LC[Loop Controller<br/>bounded loops]
end
subgraph EXEC["Execution Β· the only actors"]
RW[Retrieval Worker<br/>read-only]
EW[Execution Worker<br/>scoped tools]
AR[Archivist<br/>docs only]
V[Verifier<br/>read-only]
end
subgraph OVER["Oversight Β· guardians, no tools"]
M[Monitor<br/>safety + intent]
Q[QC<br/>correctness + quality]
S[Security<br/>integrity + HALT]
end
subgraph ADAPT["Adaptation"]
L[Learning<br/>propose only]
E[Evaluator<br/>measure, read-only]
N[Nurse<br/>conditional triage]
end
H --> A --> R --> T
A -. loop_request .-> LC
LC -. iteration .-> T
LC -. loop_complete .-> A
T --> EW
T --> AR
R -. retrieval .-> RW
Q -. verify .-> V
EW --> M
AR --> M
M --> Q
M --> S
Q --> S
Q -. iteration_result .-> LC
S -. halt / quarantine .-> EXEC
L --> E --> M
R -. checkup_request .-> N
AU[(Audit)] -. triage_signal .-> N
N -. report / repair manifest .-> M
S --> H
The only column that can affect the world is a single role (Execution Worker). The only roles that can veto or halt are tool-less guardians and the human. The Loop Controller drives bounded loops but holds no tools; the Evaluator gates self-improvement but only measures; the Nurse diagnoses harness health but repairs only through normal gated actors.
flowchart TD
U([user_request]) --> A[Alpha<br/>resolve intent, set intent_ref]
A -->|request_manifest| M1{{Monitor}}
M1 -->|FAIL| XR[refuse]
M1 -->|PASS| RT[Router<br/>plan + what to retrieve]
RT -->|retrieval_manifest| RW[Retrieval Worker<br/>read-only]
RW -->|retrieval_result| M2{{Monitor<br/>scrub injection}}
M2 -->|PASS| RT
RT -->|task_manifest| TM[Taskmaster<br/>assignments + JIT creds]
TM -->|assignment| EW[Execution Worker<br/>only granted tools]
EW -->|work_result| MS{{Monitor<br/>safety Β· two-axis}}
MS -->|FAIL| BL[block]
MS -->|PASS| QG{{QC<br/>vs definition-of-done}}
QG -. verify_spec .-> VF[Verifier] -. verify_result .-> QG
QG -->|FAIL Β· n < max| TM
QG -->|PASS| AGG[Taskmaster<br/>aggregate]
AGG -->|aggregate_result| M3{{Monitor}}
M3 -->|PASS| AC[Alpha<br/>compose]
AC -->|response| M4{{Monitor<br/>final safety gate}}
M4 -->|PASS| RESP([response])
M4 -->|verdict| SE
MS -->|verdict| SE[[Security]]
QG -->|verdict| SE
SE -. HALT / quarantine .-> EW
SE -. escalation .-> HU([human])
Deciders emit manifests but never touch tools. Retrieval is delegated, then scrubbed. The Taskmaster mints least-privilege credentials per assignment. Every worker result is double-gated: safety first, then quality. Even the final response is Monitor-gated before human delivery. Security sees every verdict on a side channel, so it can HALT independently.
Driven by the tool-less Loop Controller, a task can run as a self-correcting loop instead of a single pass, but only under guardrails that answer the three ways loops fail in production (infinite loops, goal drift, cost explosion):
flowchart LR
A[Alpha] -->|loop_request| LC[Loop Controller]
LC -->|iteration_assignment| TM[Taskmaster β Worker]
TM --> GATES{{Monitor β QC β Verifier}}
GATES -->|iteration_result<br/>+ verified evidence| LC
LC -->|loop_state_update| LG[(loops/ ledger)]
LC -->|stop?| D{verified done?<br/>or budget hit?}
D -->|not yet| TM
D -->|done / budget_exhausted / no_progress| A
- Budgets are mandatory: max iterations, wall-clock, cost, no-progress patience. A budget hit stops and reports; it is never extended to "just finish."
- The stop condition is externally verified by the Verifier through QC, never a self-reported "done." A loop with no checkable done-test is rejected.
- Each iteration starts from a fresh context rebuilt from the
loops/ledger, including the log of prior failed attempts, so dead ends aren't repeated (the Ralph pattern). intent_refrides through unchanged, so the Monitor catches drift on every pass, and Security can HALT a runaway from any state.
Every iteration is a full pass through the normal safety mesh; looping repeats the gated cycle, it doesn't bypass it. Full detail in docs/LOOPING.md.
The mesh improves the way a careful engineering org does: it accumulates measured, reversible lessons, not new permissions. The design is governed Reflexion, with the proposer and the evaluator kept deliberately separate:
flowchart LR
AU[(audit log)] -->|signals| L[Learning<br/>reflect + propose]
L -->|proposed_improvement| E[Evaluator<br/>shadow-test on held-out experience]
E -->|measured_improvement| M{{Monitor<br/>safety review}}
E -->|unmeasured / regressing| RJ[rejected β audit]
M -->|weakens a constraint| FL[flagged β audit]
M -->|non-safety| S[[Security ratify]]
M -->|safety-adjacent| HU([Human ratify])
S & HU -->|backpack_commit| BP[(backpacks/<br/>append-only, versioned)]
- Measured before adoption. Learning can only propose a falsifiable lesson; the Evaluator shadow-tests it against held-out episodes in
experience/and forwards it only if it shows real benefit with zero regressions. - Independent evaluation. The Evaluator runs on a different model lineage than Learning, the documented mitigation for degeneration of thought (a model reinforcing its own flawed reasoning).
- Append-only and reversible. Commits are versioned and ratified (Security for non-safety, a human for safety-adjacent); retiring a lesson writes a tombstone, never a deletion.
- Bounded. Lessons and playbooks may tune how the mesh works; they may never grant capability, alter the constitution, or weaken a gate.
A mesh that improves gets better at its job but can never expand its own authority. Full detail in docs/SELF-IMPROVEMENT.md.
| Agent | Plane | Holds tools? | Can it act? | Veto / control |
|---|---|---|---|---|
| Alpha | intent | no | no | none |
| Router | orchestration | no | no | none |
| Taskmaster | orchestration | no (mints credentials) | no | none |
| Loop Controller | orchestration | no | no | drives bounded loops |
| Retrieval Worker | execution | read-only | reads only | none |
| Execution Worker | execution | yes, per JIT grant | yes (scoped) | none |
| Archivist | execution | docs write only | docs only | none |
| Verifier | execution | read-only (sandboxed) | reads only | none |
| Monitor | oversight | no | no | reject |
| Quality Control | oversight | no | no | rework |
| Security | oversight | no | no | HALT |
| Learning | adaptation | read audit | no | propose only |
| Evaluator | adaptation | read-only (sandboxed) | measures only | gate self-improvement |
| Nurse | adaptation | read-only diagnostics | diagnoses only | repair manifests via Monitor |
The three guardians ask three independent questions. Monitor: is this safe and faithful to the original intent? QC: is this correct and complete? Security: is the whole system behaving? None can act.
polos/
βββ AGENTS.md β DOX root + AGENT ENTRY POINT (an agent starts here)
βββ BUILD.md β bootstrap: how an agent builds the mesh in any stack
βββ PROJECT_CONTEXT.md β user-editable project context (stack, deploy targets, conventions, gotchas)
βββ README.md β you are here
βββ models.yaml β model binding (OpenRouter-style); tiered by role, swap a model in one line
βββ mesh.config.yaml β enabled roles, tiering, loop + improvement budgets, fail-closed limits
βββ pyproject.toml β installable `polos` package + `polos` CLI entry point
βββ LICENSE Β· NOTICE β AGPL-3.0
βββ CONTRIBUTING.md Β· CODE_OF_CONDUCT.md Β· SECURITY.md Β· CHANGELOG.md
β
βββ constitution/ β IMMUTABLE rules (authoritative)
β βββ core.md invariant, ceilings, tiering, Β§Looping, Β§Self-Improvement, Β§Harness Triage
β βββ AGENTS.md
βββ roles/ β canonical agent definitions (source of truth)
β βββ _TEMPLATE.agent.md the rigid card shape every role fills
β βββ alpha Β· router Β· taskmaster Β· loop-controller .agent.md (intent / orchestration)
β βββ retrieval-worker Β· execution-worker Β· archivist Β· verifier .agent.md (execution)
β βββ monitor Β· qc Β· security .agent.md (oversight)
β βββ learning Β· evaluator Β· nurse .agent.md (adaptation)
β βββ AGENTS.md roster + capability matrix
βββ contracts/ β the connection layer (guarantees no gaps)
β βββ envelope.schema.json the one message shape every hop uses
β βββ flow.graph.yaml every edge + gate + completeness invariants I1βI15
β βββ state-machine.md every state + PASS / FAIL / UNCERTAIN transition
β βββ schemas/ payload schemas for 39 graph message types + episode/environment/project context
β βββ AGENTS.md
βββ oversight/ β the three guardian policies (safety / quality / integrity)
β βββ AGENTS.md
βββ adapters/ β stack mappings (additive)
β βββ generic.md Β· vscode-copilot.md Β· langgraph.md
β βββ AGENTS.md
βββ tools/ β the structural validator + CI dependency
β βββ validate_mesh.py Β· requirements.txt
β βββ AGENTS.md
βββ polos/ β Polos Core Runtime: installable CLI + governed execution (Python)
β βββ cli.py polos validate Β· init Β· plan Β· run --dry-run Β· audit Β· version
β βββ contracts/ Β· runtime/ task contracts, role boundaries, grants, approvals, sandbox, loop controller
β βββ policy/ Β· tools/ fail-closed policy engine + governed tool gateway
β βββ audit/ Β· verification/ hash-chained audit log + evidence-producing checks
β βββ models/ Β· adapters/ provider-neutral model router + host adapter interfaces
β βββ evaluation/ authority-preserving measured-improvement scaffold
β βββ AGENTS.md
βββ tests/ β runtime tests (policy, grants, gateway, loop, CLI, verification)
β βββ AGENTS.md
βββ loops/ β runtime: per-loop append-only ledger (the loop's source of truth)
β βββ AGENTS.md
βββ experience/ β runtime: episode records, the held-out set the Evaluator measures on
β βββ AGENTS.md
βββ environment/ β runtime: redacted host/provider profile for playbook matching
β βββ AGENTS.md
βββ backpacks/ audit/ β runtime: ratified lessons/playbooks (versioned) / hash-chained decision log
β βββ AGENTS.md (each)
βββ docs/ β human-facing, DERIVED documentation
β βββ ARCHITECTURE.md rationale, diagrams, threat model, prior art
β βββ LOOPING.md safe loop engineering
β βββ SELF-IMPROVEMENT.md measured, governed Reflexion
β βββ PLAYBOOKS.md environment profiles + repeatable task playbooks
β βββ NURSE.md conditional harness checkups + repair manifests
β βββ EXAMPLE-TRACE.md a worked request trace
β βββ AGENTS.md
βββ .github/ β CI workflow + issue / PR templates
βββ workflows/validate.yml
βββ PULL_REQUEST_TEMPLATE.md
βββ ISSUE_TEMPLATE/
Every durable directory carries an AGENTS.md (DOX) describing what it owns. The Archivist keeps them current and reachable from the root index.
All model selection lives in models.yaml. A single profile flips the whole mesh; any role can be pinned in one line. IDs are explicit provider/model strings, with no opaque tiers. Profiles bind four classes mapped to three model tiers plus diverse-lineage oversight:
| Class | Tier | Roles | Example models |
|---|---|---|---|
decider |
big-thinking | Alpha, Router, Taskmaster, Loop Controller | gpt-5.5, claude-opus-4.8 |
worker |
cheaper-thinking | Execution Worker, Archivist, Learning, Nurse | glm-5.2, qwen-3.7-plus |
fast |
fast-process | Retrieval Worker, Verifier | gemma-4, grok-4.3, gpt-5.4-mini |
oversight |
diverse lineage | Monitor, QC, Security, Evaluator | different family than decider/worker |
profile: balanced # thinking | balanced | fast
profiles:
balanced:
decider: openrouter/qwen/qwen-3.7-plus # cheaper-thinking: plans + decides
worker: openrouter/zai/glm-5.2 # cheaper-thinking: produces work
fast: openrouter/google/gemma-4 # fast-process: retrieval + checks
oversight: openrouter/xai/grok-4.3 # diverse lineage vs decider/worker
roles:
alpha: { class: decider }
retrieval-worker: { class: fast }
monitor: { class: oversight }
evaluator: { class: oversight } # measures improvements; kept off the worker's lineage on purpose
security: { class: oversight, model: openrouter/anthropic/claude-opus-4.8 } # one-line pinOversight (and the Evaluator) resolve to a different model lineage than deciders and workers, so a jailbreak that fools an actor doesn't automatically fool its guardian, and a flawed proposer doesn't get to grade its own idea. The validator fails if oversight collapses to the same model as decider or worker. If your host exposes only one provider, default all roles to that provider and keep oversight on a different model family within it; see the "Single-provider hosts" note in models.yaml.
Replace the example model IDs with the current slugs for your gateway before running. Set
OPENROUTER_API_KEYin your environment; the building agent uses your presaved key and never prints or commits it.
Three mechanisms make the flow total, and one script proves it:
- One envelope. Every inter-agent message is a valid
MeshEnvelope, carryingintent_refunchanged end-to-end. - A complete flow graph.
flow.graph.yamlenumerates every edge and the fifteen completeness invariants (I1βI15, including the looping, self-improvement, and Nurse triage guarantees); senders never choose their own gates, and every gated edge defines anon_fail. - A total state machine. Every state defines PASS / FAIL / UNCERTAIN, defaulting to BLOCK (fail-closed).
pip install -r tools/requirements.txt
python tools/validate_mesh.py
# -> Polos validation - 14 role cards, 65 edges, 39 graph message types, 42 schemas, 423 checks
# -> PASS - every enforced completeness invariant holds.The validator checks exact edge-by-edge card handoff coverage, card-vs-graph input/output consistency in both directions, a payload schema for every graph message type, envelope hardening sentinels, model-registry sanity, the capability ceilings, the constitution-is-never-written rule, final-response gating, Security control coverage, verdict audit coverage, the looping/self-improvement/Nurse invariants (I12βI15), and DOX index reachability, then prints PASS or the exact violations. It runs in CI on every push and PR, so the mesh cannot silently drift out of integrity.
The repo uses DOX: every durable directory has an AGENTS.md that is a binding contract for its subtree, in a fixed section order, reachable from the root index. The Archivist maintains the tree, with a hard rule:
Docs describe, they do not define. The canonical specs (
constitution/,roles/*,contracts/,models.yaml) are authoritative;AGENTS.mdfiles are derived. On any contradiction, the source wins and the Archivist repairs the doc.
- Add an adapter β drop a note in
adapters/followinggeneric.md. It must explain how the host denies tools to deciders and oversight. - Add or change a role β copy
roles/_TEMPLATE.agent.md, fill the front-matter contract, add a binding tomodels.yaml, and wire its edges incontracts/flow.graph.yaml. The validator enforces that the card and the graph agree. - Add a message type β add
contracts/schemas/<type>.schema.json, the edge(s), and update the affected cards.
Run python tools/validate_mesh.py before every PR. See CONTRIBUTING.md.
| If you want to⦠| Read |
|---|---|
| Understand the design rationale, threat model, and diagrams | docs/ARCHITECTURE.md |
| Understand safe looping (budgets, stop conditions, the ledger) | docs/LOOPING.md |
| Understand measured self-improvement | docs/SELF-IMPROVEMENT.md |
| Understand repeatable task playbooks | docs/PLAYBOOKS.md |
| Understand conditional Nurse checkups | docs/NURSE.md |
| See a request flow through the mesh with example envelopes | docs/EXAMPLE-TRACE.md |
| Read the immutable rules | constitution/core.md |
| See exactly how agents connect | contracts/flow.graph.yaml |
| Build the mesh in your stack | BUILD.md + adapters/ |
Polos is free and open source under the GNU AGPL-3.0 (LICENSE). You may use, study, modify, and share it, including inside a company.
What the AGPL is here to prevent is quiet proprietary capture. If you run a modified version of Polos as a network service, the AGPL (section 13) requires you to offer your modified source to its users. In practice Polos can power your own work freely, but it cannot be forked into a closed, repackaged commercial product without giving those improvements back to the community. That is a deliberate stance: Polos is a public good for the agent-safety community, stewarded by Coeus Institute, not a product to be privatized.
If you want to build something on top of Polos that the AGPL would not allow, that needs a separate arrangement; contact Coeus Institute at https://coeus.institute.
Honest note on terms: a genuine open-source license cannot ban commercial use outright; that is part of what "open source" means. AGPL-3.0 is the strongest open-source way to keep a project open and hard to exploit. If a hard non-commercial restriction matters more than the "open source" label, a source-available license such as PolyForm Noncommercial is the alternative.
Core runtime, v0.3.0 (adds the installable Python harness, governed tool gateway, verification gates, safe looping, and measured self-improvement scaffolds). "Polos" is the project's name; forks may rename by updating README.md, NOTICE, and CONTRIBUTING.md.
Polos is created and maintained by Coeus Institute as part of its agent-safety R&D.
It draws on the reference-monitor concept, capability security / least privilege, and the "AI control" idea of a trusted weaker model supervising an untrusted stronger one; on loop engineering (Boris Cherny, Peter Steinberger, Addy Osmani) and the Ralph technique for safe loops; on Reflexion (Shinn et al., 2023) and its "degeneration of thought" failure mode for measured self-improvement; and on the DOX AGENTS.md documentation convention.