Evidence, not inference. Judgment, not automation. Signatures before action.
IRIN is a council of frontier AI models you run on your own machine. You bring it a question, several models deliberate under a chair — frame checks, flip-flop detection, budget pause, a convergence judge — and you watch the argument happen live in a War Room UI. Around the council sits a governance layer: a ruling doesn't end as text, it can leave as an Ed25519-signed, hash-chained directive that anyone can verify offline.
This is pre-release (v0.1), single-tenant software, and this README is honest about what's live: the council, the War Room, and the signing chain run today. The autonomous watchers ship disarmed by design.
- Convene a real council.
make warroom, pick a cabinet, ask a real question, watch the seats argue and converge. A free NVIDIA key puts every seat live at $0. Not a simulation — real frontier models deliberating. - Bring your own providers. The NVIDIA free tier is just the zero-cost
start. Seats also run on your own keys and agent CLIs — xAI API, Claude
CLI, Codex CLI, Gemini — see
council-rs/docs/providers.md. - Point your coding agent at it. Claude / Codex / Grok escalates evidence
to the council and gets a signed ruling back:
sentinel/docs/YOUR-AGENT.md. - Check the receipts claim.
make verifyproves the signing chain in an isolated Docker stack — $0, no keys, under two minutes.
Three pieces, separated on purpose so no single component can watch, decide, and act alone:
| Piece | What it is | What it's doing in your install | v0.1 state |
|---|---|---|---|
council-rs/ + War Room |
Multi-model deliberation engine (260+ sessions of history) and its UI | Everything you see: seats, cabinets, deliberation, rulings | Live — this is the product surface |
gateway/ |
Signing and spend-control plane | Signs rulings into directives, meters every call against hard budgets, keeps the hash-chained outbox. Runs inside the make verify stack and the full stack — not started by make warroom |
Live in the verify / full stack |
sentinel/ |
The watch protocol | Defines the deterministic watchers (evidence in, never inference) and the message envelope the other two speak | Ships disarmed — arming is a governed ceremony, not a config flip |
Nothing hidden runs on your machine: make warroom starts the council binary
and its web UI, nothing else. make verify stands up an isolated Docker
stack and make verify-down removes it.
git clone https://github.com/irinityhq/irin.git
cd irinEvery command below runs from this irin/ directory. Pick your lane — the
prerequisites differ:
For the War Room (the product — start here):
| Tool | Check | Install — macOS · Ubuntu/Debian |
|---|---|---|
| Rust toolchain | cargo --version |
rustup.rs · rustup.rs |
| Node 20+ | node --version |
brew install node · NodeSource setup |
| git + make | git --version, make --version |
xcode-select --install · sudo apt install git make |
For make verify (the proof — no Rust or Node needed):
| Tool | Check | Install — macOS · Ubuntu/Debian |
|---|---|---|
| Docker + Compose v2.24+ | docker compose version |
Docker Desktop · Docker Engine docs |
| git + make | git --version, make --version |
xcode-select --install · sudo apt install git make |
| curl, openssl, python3, jq | jq --version etc. |
brew install jq openssl python · sudo apt install curl openssl python3 jq |
Get a free NVIDIA API key at https://build.nvidia.com — no card required — and export it:
export NVIDIA_API_KEY="nvapi-..."
make warroomThe first run builds the council binary and installs the web dependencies,
then serves the War Room at http://127.0.0.1:3010. Select the
starter-nvidia cabinet — built for exactly this one-key setup — and put
a real question to it.
The free key talks to NVIDIA's hosted API — no local GPU, no CUDA. Apple Silicon and Linux both run the stack natively.
On our own launch morning we filed a real question from our security board — expose the gateway's watch endpoints, or keep them dark? Three seats argued, convergence scored 78%, and the chair filed the ruling: keep them dark until multi-tenant auth lands. The same call our human review reached.
Now use it:
- Ask something you actually care about. A design decision, a risk call, a review. Watch the seats take positions, challenge each other, and converge — or refuse to.
- Change the room. Cabinets and deliberation modes are configuration, not
code:
council-rs/docs/war-room.md. - Add seats on your own keys. xAI API key, Claude CLI, Codex CLI, Gemini
— each provider you already pay for becomes a seat:
council-rs/docs/providers.md. - Wire your agent in. Your Claude / Codex / Grok agent escalates evidence
and receives rulings:
sentinel/docs/YOUR-AGENT.md.
A council's rulings wouldn't mean much if the record could be edited after the fact. IRIN's claim is that every ruling can leave as a canonicalized (RFC 8785 JCS), Ed25519-signed row, hash-chained to every row before it — verifiable offline by anyone with the public key.
make verify proves that claim on your machine — you're not verifying your
install, you're verifying us:
make verifyNo API key, no account, no spend. First run pulls the official images
(~60MB); then the loop closes end to end: a trigger row goes in, a local
deterministic endpoint stands in for live Council, Gateway signs, and one
Ed25519-signed directive row lands in the outbox with its full chain intact.
Under two minutes. make verify-down tears it all down.
- Run the full stack — Gateway and Council together, real providers,
metered spend:
gateway/docs/operator-quickstart.mdandcouncil-rs/docs/operator-guide.md. - Read the architecture — the watch grammar, the comms envelope, and why
watchers never reason:
sentinel/docs/andsentinel/COMMS_CONTRACT.md. - The loop, end state: deterministic sentinels watch and escalate → council deliberates → gateway signs the ruling into a budget-capped directive → the signed outbox is the record. v0.1 ships the deliberation and signing legs live; watchers are present but disarmed until armed in a governed ceremony.
| Path | Role | Start here |
|---|---|---|
council-rs/ |
Deliberation engine and War Room — the product surface | council-rs/README.md, council-rs/docs/war-room.md |
gateway/ |
Policy gateway, signed directive enforcement, verification stack | gateway/README.md, gateway/COUNCIL_GATEWAY_CONTRACT.md |
sentinel/ |
Sovereign protocol crate, watch-plane contracts, operator docs | sentinel/README.md, sentinel/COMMS_CONTRACT.md |
The root Cargo workspace includes council-rs, gateway/sidecar-rs, and
sentinel/sovereign-protocol: path dependencies resolve locally, Rust gates
share one target directory, and supply-chain checks run once at the root.
Integration channels around the core. None is required for the War Room or
for make verify.
irin-hermes-plugin— Hermes agent bridge (Node CLI): Hermes evidence -> Council escalation -> Kanban card. https://github.com/irinityhq/irin-hermes-pluginhermes-plugin-irin— native Hermes plugin surface (pure Python,plugin.yaml+register(ctx)) for the same escalation/card wiring. https://github.com/irinityhq/hermes-plugin-irinxmcp-core— X/bookmark-intelligence MCP server (bring your own X credentials). Feeds the Sheldon validator live X evidence when configured; without credentials it degrades to web evidence by design. https://github.com/irinityhq/xmcp-core
Pre-release (v0.1), single-tenant, canary-proven in the current operating shape. The mono-repo is assembled from full-history subtrees; root CI owns the union gates for Rust, secret scanning, audit, and SBOM generation. Subtree workflow files are historical references only.
- War Room notes:
council-rs/docs/war-room.md - Providers (your keys, your CLIs):
council-rs/docs/providers.md - Council operator guide:
council-rs/docs/operator-guide.md - Agent onboarding:
sentinel/docs/YOUR-AGENT.md - Security policy & threat model:
SECURITY.md - Gateway operator docs:
gateway/docs/operator-quickstart.md - Gateway contract:
gateway/COUNCIL_GATEWAY_CONTRACT.md - Sentinel operator manual:
sentinel/docs/operators-manual.md - Shared protocol crate:
sentinel/sovereign-protocol