setup

One binary. Then the room.

install

Four paths, one binary

The installer is POSIX sh, needs no Go and no sudo, and lands one file in ~/.local/bin. The release asset is the same binary with the same checksums. rig -update fetches, verifies and installs atomically; the running process keeps the old binary until you restart it.

the rig home

~/.rig is the machine's state

The home resolves $RIG_HOME over ~/.rig, and every file in it is optional except the model table's content: the binary ships no model rows. A present-but-malformed file refuses at start, naming the file and the field; unknown keys refuse too. This is a contract, not a filter.

~/.rig/
  settings.json      the knobs, flat, by their env names
  models.json        the model table: one row per model
  AGENTS.md          your standing instructions, ahead of the project's
  theme.json         the terminal palette (custom base + slots)
  sessions/          the state store: transcripts, usage, resume
  todo/              the task board: one file, rows carry the project scope
  rem/               memory, scoped to the repo (worktrees share)
  graph/             the code map: symbols, edges, files per worktree
  decision/          the decision store, and train/ with its jsonl splits
  plugins/           live, pending/, disabled/
  train/             the decision model's trainers, its own zone
  room/              the machine's unix sockets
  logs/              the models' children and what they served

Every knob resolves through four layers, per key: flag > env > file > embedded default. A flag you typed always wins, whatever its value; an empty env or file value descends, except the two presence keys (RIG_WEB_FETCH_PROXY and RIG_TRAFILATURA), where "set empty" is an explicit choice. On a start where the home is absent and the old ~/.config/rig exists, it is renamed once and says so.

{
  "model": "local",
  "baseUrl": "http://127.0.0.1:8090/v1",
  "sandbox": "jailed",
  "approve": "auto",
  "theme": "warm"
}

# how I like to work
- run the tests before you say it's done
- prefer small commits, one idea each
- never add a dependency without saying why

The project's own AGENTS.md is the nearest one walking up from the workspace to the repository root, and no further: a session opened in a subdirectory reads the repo's contract, a workspace that is no repository reads only its own file. It is read when the session wires, so a session carries the contract of the workspace it opens in.

the router

rig is the router, and there is no router process

Since 3.0.0 nothing routes in front of your models. llama-swap left the stack and nothing took its place. Every rig instance on the machine joins one room over a unix socket under the rig home, and the model is a guarded key in that room: an instance sends its request to the model's port itself, once its claim is final by every live member's acknowledgement.

The order is the operation, not a process. A claim carries its mint, its key and its priority; every member folds the same fields the same way — priority first, then tick, member, nonce — so a late act takes its rightful place and a duplicate is refused by its mint. The classes are the room's priorities:

 90  the operator's turn
 70  a delegate's return
 30  a fleet worker's claim
 20  a child's start or stop
  0  an outside client

Inside a turn the batch has its own two rungs — a write 60, a read 50 — and those are the kernel's order, not the room's.

A claim that finds the row's port silent holds its place, publishes the start, and sends when the port answers. When another row is resident it publishes the swap on that row's key instead, so the resident one stops at its holders' end and before the incoming one starts. One child at a time — the rule the retired router had, now an order. What is loaded is read from the world, never replayed: the port is probed at a join, and a child's /health saying 503 is what "still loading" means.

mesh in settings.json extends one room to many machines: a TCP door the tailnet reaches, gossip converging the machines' folds. The mesh's order is advisory — a key's home machine is its authority — and a foreign claim past the horizon reposts at the home machine, where that row's child runs. The cost is one horizon at the front of a remote request, about 1.3 s at the defaults, measured on loopback.

models

Loading and unloading are claims and swaps

A model row is the whole model: its window, its budget, its dials, and — when the machine serves it — the child half. The child half is how a row says "I know how to start this model", and nothing else starts it:

The row with its child half, and a hosted row beside it:

[
  {
    "id": "local",
    "window": 393216, "maxTokens": 65536,
    "reserve": 104858, "keepRecent": 98304,
    "effort": "xhigh", "efforts": ["low", "medium", "xhigh"],
    // the child half:
    "command": "llama-server -m ~/models/qwen.gguf --port ${PORT} -np 2",
    "port": 8090,
    "aliases": ["qwen"],
    "stopGrace": 10,
    "places": 2
  },
  {
    "id": "sonnet",
    "window": 200000, "maxTokens": 8192,
    "reserve": 16384, "keepRecent": 40000,
    "provider": "openrouter",
    "baseUrl": "https://openrouter.ai/api/v1",
    "apiKey": "sk-or-…",
    "reasoning": "reasoning"
  }
]

Loading is a claim that found the port silent: the instance publishes the start and waits for the port, and the child is the row's own command. Unloading is a swap's stop, ordered on the resident model's key, at the holders' end and before the incoming start — never eviction of a request mid-flight. A strictly higher-priority claim may enter while the places are full; the entry is one holder beyond the places, never eviction, and a same-priority claim queues for a place. Between claims, the continuation wins: within one priority, the claim naming the conversation already in the model goes first, because a dropped reply costs a full prompt re-read.

Inside a session, the verbs are the same table:

the faces

The TUI, or the page — one session

Four frontends run over one session: the TUI, the piped CLI, the -p one-shot, and the web dashboard. They are not four products with four states; they are four doors onto the same loop, the same stores, and the same commands.

The dashboard is the only face for the room: there is no slash command for it. The TUI is the only face for memory: there is no memory view on the page — rem is the model's, read in the terminal.

scheduled workers

The crontab is the clock

A scheduled job is a one-shot rig -p in its own cwd, on your crontab, wrapped in the sandbox profile of your choice. The crontab is the scheduling truth; the store is its audit and its repair. A job's fire is its own process, so it cannot outlive the schedule.

# crontab — the job's key is its one positional
0 */2 * * *  rig run-job j8-health

# or from inside a session, the same store:
/scheduler create health "check the fund" 0 */2 * * *

Each job carries its own timeout and budget; a model that is not resident refuses by name, naming the holder. The interactive REPL and one-shot runs never consult the sandbox code: the jail is for work that outlives you.

verify

Four checks, no trust

# 1. the binary
rig --version

# 2. the endpoint, with the model row you wrote
rig --base-url $YOUR_ENDPOINT --model $NAME --system "be terse"

# 3. the terminal: the three-row status, a streaming turn, a tool line
# 4. the same session to a capturable pane
tmux new-session -d 'rig --tui=true' \; capture-pane -p

If nothing streams, check the endpoint first: rig surfaces provider faults verbatim and loudly, and does not hide them. The piped path (--tui=false) is the byte reference — the TUI adds to those bytes, never changes them.

gotchas

The refusals you will meet first