--- title: "avsmd" summary: "The obedient paperclip maximizer daemon that won't keep you up at night." external_url: "https://github.com/4esv/avsmd" links: - "https://github.com/4esv/avsmd" --- - Stars: 0 - Language: Rust - Updated: 2026-10-24 - License: Apache-2.0 [GitHub](https://github.com/4esv/avsmd) The obedient paperclip maximizer. An agentic daemon that pursues the goals you give it, acts only within the limits you set, and has proof for everything it does. avsm supervises ventures. A venture is a directory with a mandate: what it is for, what number to watch, what it may do, what it may not. avsm keeps the venture's process running, reads its metric on a cadence, and once a night lets a model choose between doing nothing, taking an action the mandate permits, or asking you. Every record in its ledger is measured by code, declared by a human, or inferred by a model. An action is accepted only if a proof exists from measured and declared facts under a mandate, and `avsm why` prints that proof. Models propose. Code proves. Nothing a model says can authorize anything by itself, so leaving avsm running overnight is safe because harm is underivable, not because the model is good. You wake up to work done, not work to do. ## Install cargo install avsmd Or from source: git clone https://github.com/4esv/avsmd cd avsmd cargo install --path . Two binaries: `avsmd`, the daemon, and `avsm`, which gives it commands. No public listener: avsmd answers over a Unix socket in its home, `~/Library/Application Support/avsmd` on macOS and `$XDG_STATE_HOME/avsmd` (`~/.local/state/avsmd`) on Linux, or `$AVSMD_HOME`, or `--home`. A Unix socket path is limited by the system, 103 bytes on macOS and 107 on Linux, and the socket is `sock` in the home, so keep the home short: a longer one fails with `use a shorter --home or AVSMD_HOME`, and `avsmd -t` and `avsm doctor` say so before then. ## Add a venture Start the daemon. It runs in the foreground, so give it a terminal or a service (see Running it): avsmd In another terminal, take on the example venture: avsm add examples/counter `examples/counter` holds three files. `report` prints a number, one higher each time it runs; the program that reads a venture's metric is always named `report`, beside the mandate, unless the metric names a built-in one. `reset` puts the number back to zero. `mandate.yaml` says what to do about it: ```yaml purpose: Keep the counter below ten. metric: count controller: kind: threshold above: 10 action: reset cadence: 10s permitted: - name: reset run: ./reset cap: 60/hour reversible: true forbidden: [rm] ``` Watch it work: avsm status avsm tail A duration (`cadence`, `timeout`, a cap's period) is a number and its unit: `10s`, `5m`, `2h`, `1d`. `1h30` is not one; write `90m`. The count rises by one every 10 seconds. Within two minutes it climbs past ten, avsm runs `reset`, and then does so again about every two minutes: some 33 resets an hour against a cap of 60, so the example stays inside its limit. The ledger holds the reports, the action, and the proof that allowed it. Every line is one record: its number, its time, its venture, who made it (measured, declared, inferred), what it is, and a summary. A venture directory may also hold `run`, a program avsm keeps alive and restarts when it dies (`restart: always`, `on-failure`, or `never` in the mandate). Actions are levers you install: a name, the command to run, how often it may run, and whether it can be undone. avsm never runs an irreversible action on a model's word. It asks instead; `avsm asks` lists the questions, `avsm approve ` and `avsm deny ` answer them. Write `delegated: true` on an irreversible action to let it run unasked; avsm then records its intent before and the outcome after. A lever runs apart from the daemon: while it runs, commands are answered and the other ventures go on. One run may take ten minutes, or what `timeout: 30s` on the lever says; past it the run is killed and its outcome written as failed. Pausing the venture stops a lever still running, and its outcome says so. A lever may take content: `takes: text`, `json`, `diff` or `file`. A model can then propose the text of an announcement or the diff of a change, and what it wrote waits for you. `avsm asks` shows it under the question, `avsm approve --edit` opens it in your editor so what you save is what runs, and `avsm propose ` files a proposal of your own. The editor is `$VISUAL` when it is set, else `$EDITOR`, else `vi`; it needs a terminal, so with a terminal editor and no terminal `--edit` waits for nothing. Content a model produced runs only after a human approves it, unless the mandate delegates the lever. `avsm pause ` stops a venture and nothing but `avsm resume ` starts it again. `avsm approve` of a paused venture's ask is refused: the gate would spend the approval without running it, so resume first; `avsm deny` is answered whatever the state. A resume while a guard still reads past its bound goes through, and says the guard will pause it again. There is no other steering. To change what a venture may do, edit its mandate and run `avsm add` again; the old permissions end with the old mandate. A venture's name is the name of its directory, one word of letters, digits, `_`, `-` and `.`; `examples/counter` is `counter`, and moving or renaming the directory makes a new venture. Every program of a venture (`report`, `run`, the levers) runs in that directory, so `./reset` means the `reset` beside the mandate. There is no remove: a venture is never deleted from the ledger, and `avsm pause ` is how you stop one. `avsm doctor` only notes a paused venture whose directory has gone. ### Guards, audits and plausibility A guard is a reading of its own that the warden takes beside the metric, with a bound. Past it, the guard pauses the venture (`then: pause`, the default) or asks once (`then: ask`); either way no lever but stop runs until the reading is back inside, whatever approves it. Every lever of the venture is refused, a band's corrective one and a delegation too; only stop and the guard's own unwind pass. A failed or implausible reading neither trips a guard nor clears it. A guard may not read a lever's command or the metric's. A drawdown guard falls from the metric's peak. A guard may declare an `unwind`: one permitted lever and the exact payload it takes, which the kernel runs once per episode when the guard trips (and on later readings past the bound until it has run ok), under the lever's cap, budget and check; the same lever with any other payload stays refused: ```yaml guards: - {name: spend, run: ./spend, above: 100} - {name: errors, adapter: http.status https://example.com/health, above: 299, then: ask} - {name: dd, drawdown: 15%, of: equity, unwind: {action: trade, payload: {side: sell, qty: 100000}}} audits: - {name: refunds, run: ./refunds, worse: up, tolerance: 2} range: [0, 100000] max_step: 5000 ``` An audit asks when the metric improves over its last `window` readings (5 unless set) while the audit gets worse by more than its tolerance. The metric improves going up unless the audit says `better: down`, as for unread mail. No model ever sees an audit reading. A report outside `range`, a step past `max_step`, a flap, a NaN or a failed report is kept, marked implausible, never acted on, and asks once until a plausible report comes. A guard's or audit's failed reading holds the venture implausible just as the metric's does; `avsm status` names the reading that holds it, and what clears it. With `max_step`, the report right after an implausible one is unconfirmed: kept and shown, never acted on, until the next agrees with it within `max_step`; `confirm: false` on the mandate, a guard or an audit acts on it at once, where waiting costs more than a misreading. Where a metric moves faster one way than the other, `max_rise` and `max_fall` bound each way, in place of `max_step` or beside it: stock that arrives by the pallet and leaves by the day takes `max_rise: 800` and `max_fall: 300`, and a fall to 0 from 398 is implausible though a delivery of 600 is not. Beside `max_step`, each must be smaller than it and bounds its way tighter; a way bounded by neither is unbounded. On a threshold, `deadband: 2` acts once and again only after the metric comes back past the bound by 2; `hold: 3` acts after three crossed reports in a row. A deadband means one action per excursion, whether or not the lever then ran and even if the metric is still past the bound after it; on a band, one for each side. Leave it off where one run only nudges the metric and the lever should go on running, within its cap, until the metric is back inside. A report's number is its last non-empty line, and that line is the number alone (`count: 5` is a failed report). Text before it is dropped for the metric and for a guard, whose record carries no note. For an audit the lines above the number are the note, at most 2000 characters, which a payload check may read and no model sees. A command that exits non-zero or prints no number is a failed report, kept with a note that says why. A reading is what a model may see that it could not otherwise: its command prints lines and then a number, and the warden keeps only the lines that are fields of the kind `lines` names (`address`, the one kind: text, an @, text, no spaces or `<>,;:`, at most 254 characters), at most 50 of them, joined by spaces. With `audit:`, a field is kept only when that audit's latest reading names it, so the model learns who is waiting and never what they wrote. A failed reading keeps no note at all. Its record, `reading.`, is inferred: it reads the open world, so it shows and never authorizes, and a payload check that wants a sender still reads the audit: ```yaml audits: - {name: customers, run: ./customers, worse: up, better: down} readings: - {name: waiting, run: ./waiting, lines: address, audit: customers} ``` A band holds the metric between two bounds, with a lever for each side: ```yaml controller: {kind: band, low: 19, high: 24, below: heat, above: cool} ``` Below `low` it runs `below`, above `high` it runs `above`, and in between it runs neither. Each side acts as a threshold does, with the band's `deadband` and `hold`; the deadband must be less than the band is wide. A lever for the low side may only declare `expects: up ... within ...` and one for the high side `expects: down ...` (see Expecting an effect, below); `expects` always carries `within`, so `expects: up` alone is refused. ### Doing something every hour There is no schedule: a venture watches a number. To run `backup` every hour, watch how long ago it last ran. `report` prints the age of a stamp the lever touches, making the stamp first so a missing file is not a reading of 56 years: ```sh #!/bin/sh [ -e stamp ] || touch stamp echo $(( $(date +%s) - $(date -r stamp +%s) )) ``` ```yaml purpose: Back up every hour. metric: age controller: {kind: threshold, above: 3600, action: backup} cadence: 1m permitted: - {name: backup, run: ./backup && touch stamp, cap: 2/hour, reversible: true} max_rise: 120 ``` Bound the rise only: the age falls to 0 after every run, and a `max_step` would call that fall implausible. ### Expecting an effect A lever may say what a run should do to the metric: ```yaml permitted: - {name: water, run: ./water, cap: 4/day, reversible: true, expects: up 5 within 3} - {name: vent, run: ./vent, cap: 4/day, reversible: true, expects: down within 2} ``` The syntax is `up` or `down`, then optionally a size (a number above 0), then `within` and a count: `up 5 within 3`, `down within 2`. `within` counts reports: the trusted, plausible readings of the metric that follow the run's successful outcome, not minutes or runs. The count-th such report is compared with the last reading before the run, net of what the metric was doing anyway. avsm writes a record when the run missed, or showed its effect later than `within`; a run that did what was expected writes nothing. Until the count-th report the verdict is waiting. Without a size, any move the right way beyond the metric's own noise is enough; with one, a move far off it is the wrong size. Absence of evidence is not a miss. With fewer than 3 steps of history the metric's drift is not known, and the run is not judged. A span of exact repeats of the reading before the run may be a sensor that has not refreshed, as a cached `df` read more often than it updates is. The run waits, and its lever with it, until a reading differs or the metric's own history makes that many repeats in a row less likely than 1%. A metric that has never changed is no evidence either way, and its runs are not judged. With `revoke_after: n` on a delegated lever, n misses in a row suspend the delegation until you approve the ask it raises. A lever with `expects` also gives the forecast and the capacity check an effect to start from before it has run enough to be measured. ### World models `world: ./world` names a command that steps the venture's world: a JSON state, a lever or none, a seed, the time and the last 200 trusted reports in; a state, the metric and any guard readings out, bounded to 64 KiB, with everything that is not a field dropped. Without one, the built-in baseline resamples the metric's own drift and each lever's measured effect from the ledger. With `world:` or `calibration: 0.1`, every report brings a one-step prediction, an inferred record; the next trusted, plausible report resolves it, and code scores it as a measured `calibration.` report (CRPS and its skill against persistence, Brier for guard events, 80% coverage). Below the `calibration:` bar over the last 20 scores, or with fewer than 5, a ranking from the model asks and never runs. A prediction never authorizes anything. ### Letting a model choose With `controller: {kind: model}` (or `kind: classifier`, which answers with one word), once a night avsm shows a backend the mandate and the recent records and takes its reply as a proposal, a question for you, or nothing. Backends are named in `config.yaml` in the home; any API in the Anthropic or OpenAI style works, and so does a local command, so a classifier you trained yourself fits: `nightly:` is the local time of the machine avsmd runs on, as `HH:MM`, or `never`; a change of daylight saving time moves it with the clock. ```yaml nightly: "03:00" default: anthropic backends: anthropic: { kind: anthropic, model: claude-opus-5-5, key: anthropic } deepseek: { kind: openai, url: https://api.deepseek.com/v1/chat/completions, model: deepseek-chat, key: deepseek } local: { kind: openai, url: http://127.0.0.1:11434/v1/chat/completions, model: llama3 } mine: { kind: command, run: /opt/mine/classify } ``` Other keys in `config.yaml`, each optional (`avsmd -T` prints them all as they stand): `ratchet: 5` is the approvals of one lever that make `self` propose delegating it, 0 for never; `forecast: {days: 30, seeds: 16}` (the default, which `avsmd -T` prints as a comment when you leave it out, and `canary_asks: null` for off) is how far and how wide the forecasts at add, before a ratchet ask and in a decision packet look, and `seeds: 0` turns them off; `canary_asks: {every: 20}` writes a canary ask after that many asks, and is off when absent; `port: 2876` is the tailnet port; `adapters:` says where `stripe` and `github` reach, each `{url: ...}`, and how `mail.send` sends, `mail: {command: "sendmail -t -i", from: you@example.com}`; an `anthropic` backend also takes `url` and `effort` (`low` to `max`), and a `command` backend `offbox`. A decision packet's forecast is 7 days by 8 seeds until `forecast:` says otherwise. A forecast runs apart from the kernel: commands are answered and guards read while it runs, and the forecast at add is written when it is done. It is fit to the readings no plausibility check doubts, held to the metric's `range:`, and shown to the precision of its readings, at most two decimals; on fewer than three lever-free steps of history, or with a spread the history cannot account for, it says `too little history to forecast` instead of numbers. A re-add of an unchanged mandate is not forecast again. avsmd reads `config.yaml` once, at start: after an edit, restart it, and `avsm add` says `config.yaml changed on disk; restart avsmd to apply it` while the file and the daemon differ. Keys go in `keys` in the home, one `name=value` per line, readable by you alone. Only the warden, the one process avsmd starts that may act, ever reads them; the process that talks to models holds no keys and runs as `nobody` when avsmd runs as root. ### When the model cannot answer If a reply cannot be used, or is bigger than avsm will read (256 KiB), avsm can ask a second backend the same question. Name it with `escalate:` in `config.yaml`. Before the call avsm writes a measured `escalation` record (from, to, why); the answer comes back as inferred records that cite it, and the escalation then gets a measured `answer` record: the records cited, or `unusable`. An answer proposes or asks like any model reply and never authorizes. With no `escalate:`, nothing changes. `examples/backends/claude` is a ready second backend: it runs `claude -p` in safe mode with no tools, on `sonnet` unless `AVSM_ESCALATE_MODEL` says otherwise. It sends the prompt off the machine, so flag it `offbox: true`: ```yaml escalate: claude backends: claude: { kind: command, run: /path/to/avsm/examples/backends/claude, offbox: true } ``` A backend that leaves the machine (every `anthropic` and `openai` one, and a command flagged `offbox: true`) is asked only for a venture whose mandate says `escalate: offbox`. Only you can add that line: edit `mandate.yaml` and run `avsm add`. A mandate change proposed by self or the ratchet that adds it is refused. The request has a `system` and a `user` text; a `command` backend gets both as one JSON object, `{"backend", "system", "user"}`, on standard input and prints its reply, so a command that saves its input shows exactly what a model is shown. The `user` text lists the permitted levers with their caps, the children with their state and recent records, the readings, the forbidden levers, the recent records and the open asks. The reply is one JSON object on one line: ```json {"choice": "nothing", "reason": "all quiet"} {"choice": "action", "action": "discount", "reason": "slow day"} {"choice": "ask", "question": "Refund order 7?", "action": "refund"} {"choices": [{"choice": "action", "action": "reply", "payload": "..."}, {"choice": "nothing"}]} ``` A lever that takes content needs a `payload` field too: a string for `text`, `diff` or `file`, an object for `json`. `choices` carries up to five independent choices, each judged alone. A `classifier` answers one word instead: `nothing`, `ask`, or a permitted lever. Before it chooses, the model may look things up with `{"choice": "know", "topic": ""}` and `{"choice": "why", "record": 12}`, three times at most, and every look is a record. A mandate may also permit `research`, a lever that sends a question to a command you name under `research:` in the config and keeps what comes back as inferred facts, each with its source. No provider is built in; the command is the provider. ## Running it avsmd runs in the foreground and never forks. `contrib/` holds a launchd agent (`io.aesv.avsmd.plist`) and a systemd user unit (`avsmd.service`) that start it at login and again if it dies; each file says how to install it. SIGTERM or SIGINT stops it cleanly within 10 seconds: no new commands, the work in flight finishes, a lever still running is sent SIGTERM and then SIGKILL if it lingers, and its outcome is written before avsmd exits 0. A warden or roles process that dies is started again, and a measured report of self's says so; a lever it was running is asked about (`did reset happen?`), never run again blindly. Every lever, `report`, guard, audit and reading command, and `run` leads a process group of its own, and none outlives avsmd: the warden tells avsmd of each group it starts, so when the warden dies avsmd ends what it left running, and a stop, or the pause of its venture, ends the rest. Ending is SIGTERM, then SIGKILL 7 seconds later. A guard, audit, reading or adapter metric that takes longer than half a second is read apart in the warden, so the tick goes on: the venture's report waits for its metric, and a guard, audit or reading still running is written as not read until it is done. A ledger that cannot be written stops everything that would write to it: `avsm status` and `avsm doctor` say so, and avsmd tries again every 30 seconds. avsmd -t # test the config and every adopted mandate, and say what each allows avsmd -T # print the config in force avsmd -f other.yaml # read another config avsmd -d # verbose diagnostics on standard error avsm doctor # check the home, config, ledger, mandates and daemon avsm doctor --since 1234:0123456789abcdef # and that the ledger still holds this head avsm doctor --cut 1234 # with avsmd stopped: back up, then cut just before #1234 `avsm doctor` changes nothing. Each check it fails prints the command that fixes it, and it exits with the worst code it found. Both binaries exit as sysexits.h says: 64 for bad usage, 65 for input avsmd refused, 69 when no avsmd is running, 78 for a config or mandate that does not hold. The 78 comes from `avsmd -t` and `avsm doctor`, which read the files themselves, and from `avsmd` for its config. `avsmd` starts beside a venture whose adopted mandate it cannot read, since the others may be fine: it runs nothing of that venture, names it on standard error, and `avsm status` cautions that it cannot run. A mandate that `avsm add` is refused by the running avsmd is input it refused, so `avsm add` exits 65 for it, and so does `avsm propose` for a proposal the gate refuses and `avsm tail 0`. `avsm add` of a directory that is not there exits 66, as `avsm doctor` does; a file given for its directory, or a directory with `mandate.yml` for `mandate.yaml`, is 65 and says what to pass or rename. `avsm doctor` exits 0 when every check passes, and otherwise with the worst code it found, in this order: 65 a ledger that is not a database or whose chain is broken, 78 a config or mandate that does not hold, 77 a permission missing, 73 a home that is not a directory, 66 a home or mandate directory that is not there, 69 no avsmd answering. A sound ledger and no daemon running is 69. `avsm doctor --cut` exits 75 while avsmd runs on the home (stop it first), and doctor exits 64 for bad usage: a `--cut` that is not a record number, a `--since` that is not an anchor, or `--remote`. avsmd itself exits 75 when another is already running on the same home, and names its pid: each daemon holds a lock on `avsmd.lock` in the home for its life, so even with its socket deleted a second one does not start, and `avsm doctor` says the first is running but its socket is missing. Each second avsmd checks that the lock file and the socket are still its own; one deleted or replaced is made again. Should a second avsmd take the lock first, the first stops with exit 75 and says why, and from the moment the lock is another's neither it nor its warden appends anything more, so the second raises no alarm over them. `avsm doctor` fails when it finds more than one avsmd on the home, and names the pids, and when the lock file is not a file. Records go to standard output, diagnostics to standard error, and nothing is in color. A standard output that cannot be written (closed, say) is said on standard error and exits 74; one whose reader went away ends quietly. `avsm tail --since ` prints every record after that one, for a script that follows the ledger. The ledger is `ledger.db` in the home, a SQLite file with a rollback journal and `synchronous=FULL`, for tools of your own to read; open it read-only. Every record is in the main file once it is written, so deleting `ledger.db-journal` loses nothing. A ledger written in WAL mode by an earlier avsmd is moved to this journal the first time avsmd opens it; no record is rewritten. One table, `records`: `seq` (the record number), `at` (unix seconds), `prev` and `hash` (SHA-256 hex, the chain), `weight` (always 1) and `record`, the record as JSON, whose `kind` (`report`, `proposal`, `action`, `ask` and so on), `claim` (`measured`, `declared` or `inferred`) and `venture` are always present. Triggers refuse every `UPDATE` and `DELETE`, and every `INSERT` but the next record chained to the last: the ledger is append-only. A record that still does not read stops avsmd, which names it; `avsm doctor --cut ` copies the whole ledger to `ledger.db.before-cut--