IRINITY STONESTHE IRIN FIELD GUIDE

The playful docs twin of irinity.com

Five stones.
Strict separation
of powers.

The complete operator manual for IRIN's local-first deliberation stack. Every command, key, and switch, explained.

Assemble the stack Meet the stones
Sentinel Council Gateway Worker Librarian
You

Five primitives ship as stones. The Reality slot is reserved for the sovereign operator. That is you.

One signal chain, no shortcuts

Watch is cheap. Thought is rare. Action is final. Each tier earns the next, and no primitive may do another's job. Solid arrows are the supported path today; dashed arrows are deliberately not built in v0.1.

The rule that holds the gauntlet together

A Sentinel that needs an LLM to decide something is interesting is a Worker wearing the wrong label. Observer is not judge; judge is not actor. Budgets are the security model expressed as time and money. A fire decision costs at most 100 milliseconds. Each Council run gets an operator-set USD cap and bounded provider timeouts. The built-in worker loop ships disabled by default.

The five stones

Each stone is one primitive with one verb and one hard budget. Click any card for its full reference: duties, knobs, endpoints, and fine print.

Sentinel

Time stone

Watches, never speaks, never reasons.

Deterministic observers. No LLM calls in the watch loop, ever. A fire decision lands in 100 ms or less, and enabling a Sentinel arms nothing.

Council

Mind stone

Speaks, never acts.

Multi-model deliberation with assigned seats, rounds, and a chair ruling. Thought is rare, so every run gets an operator-set USD cap and provider calls have bounded timeouts.

Gateway

Space stone

Governs every call it carries.

Routing, metering, and Ed25519 signing on a loopback-only edge. Direct is the default; Governed is an explicit per-seat opt-in, never a toll booth.

Worker

Power stone

Acts, never remains.

Ephemeral execution behind authenticated claim, heartbeat, and ack routes. In v0.1 the gauntlet stops at the signed Outbox directive: the built-in worker loop is disabled by default and is not an operator-ready autonomous executor.

Librarian

Soul stone

Answers, with sources.

A live War Room tab that answers locally with sources from a local Librarian service. The wider identity, durable-memory, and CapabilityToken roadmap stays parked, marked as future work. Some stones demand patience.

The Sovereign

Reality stone

Decides. Always.

The sixth slot is not software. It is the human each tenant scope serves, and the only authority that can arm the action path. Nothing executes without you.

Assemble the stack

Two ways in. Operators install the signed app; contributors build from source. The full command reference lives on the Commands page.

The product path: the signed macOS app

One download, documented on the main site

The product is one signed, notarized DMG containing IRIN.app: the desktop shell, the bundled Council and War Room, and the optional Gateway Pack assets. No source checkout, no Docker, and no make for Direct mode. Apple silicon only; Intel Macs are not supported. For install, follow the numbered download-verify-open path on irinity.com — this site is the field guide, not the installer.

The contributor path: build from source

Start at the source

Everything below is the source/developer path for contributors, not the product install. IRIN is distributed from irinityhq/irin, with xmcp-core and hermes-plugin-irin as optional companion repositories. Run every make command from the root of the checkout; configuration and provider credentials stay local.

macOS from source: the whole gauntlet

cd irin
make setup

SourceFrom your authorized checkout: prepares private config and signing material, builds and starts Council, War Room Web, and Gateway, enables login recovery, then prints your service URLs. Preserves operator-owned values you already set.

make app-install

SourceBuilds, atomically installs, and launches the native macOS desktop shell from your checkout. It reuses the runtime make setup already started; it never starts a competing backend.

Ubuntu from source: browser War Room

make warroom

SourceBuilds and starts Council plus War Room Web in the foreground on loopback. Open http://127.0.0.1:3010, stop with Ctrl+C. This path does not install login recovery, configure Tailscale, start Gateway, or provide the desktop app.

From source, either OS: prove the loop

make verify
make verify-down

ProofRuns the Sentinel-to-signed-directive path end to end in an isolated stack: no provider keys, no hardware arming, own ports, own volumes. One signed mock directive lands in the Outbox. Details on the Ceremony page.

Where things listen

Surface
Address and notes
War Room in IRIN.app
Served same-origin by the app's bundled Council on http://127.0.0.1:8765. No source command needed.
War Room Web (source)
http://127.0.0.1:3010 - the browser UI from a source checkout.
Council API + WebSocket
http://127.0.0.1:8765 - deliberation engine, REST and streaming.
Gateway
http://127.0.0.1:18080 - off by default. On the installed app, Settings -> Enable Gateway starts the app-owned pack; from source, macOS make setup, or started separately on Ubuntu.
Desktop app
IRIN.app on macOS: from the signed DMG it starts and owns its bundled Council; from make app-install it reuses the checkout's runtime.
Private phone
https://<your-device>.<tailnet>.ts.net:8443 - Tailscale Serve only, never a public URL, enabled from the installed app's Settings. Operator/device path still in device acceptance.

The rule of this site

Every option you can click here explains itself: what it does, what it costs, and what it refuses to do. If a switch ever leaves you guessing, that is a bug in the docs, not a personality trait.

The main site is the serious one. This one is allowed to have fun, but it is not allowed to invent: budgets, defaults, and limits are quoted from the product's own docs and code. Where the product is honest about a boundary, these pages repeat that boundary word for word. IRIN is local-first software for one operator, pre-release, best-effort, and deliberation does not guarantee correctness.

Commands

Every make target, runtime subcommand, and CLI flag, tagged by who it is for: operator, source, proof, or engineering.

Config

Every environment variable and config key, with defaults and the deltas between example files and code.

Protocol

Envelopes, escalations, directives, canonical JSON, and the fences that keep stones in their lanes.

Ceremony

Arming is a ceremony, not a config flip. Touch ID or FIDO2, staged, expiring, audited.