README
¶
nova-config
What it is
nova-config: a fleet's machines and AI friends as rows in PostgreSQL, applied into Redis
Why use it
Keep fleet configuration durable.
Install
go install github.com/mas-bandwidth/nova-tools/cmd/nova-config@latest
nova-config version
First run
The transcript below is copied from the first run in docs/TESTS.md, which cmd/nova-config/firstrun_test.go executes line for line; a docs test holds this copy to that record.
No database: the first run keeps its rows in ./try.json (--file), the
same kinds, refusals and history as PostgreSQL, and
cmd/nova-config/firstrun_test.go runs each $ line in t.TempDir(). The
history's at= is the instant of the run, the one value that differs on a
second run. The real runs need a Postgres (nova-config migrate) and a Redis
(nova-config apply); docs/nova-config/README.md walks them, and
cmd/nova-config/config_functional_test.go runs them against a throwaway
Postgres and a throwaway Redis.
$ nova-config migrate --file try.json
CONFIG MIGRATE file=try.json from=0 to=36 applied=36
$ nova-config machine add m1 --user nova --seat s1 --slots 8 --width 4 --actor a1 --file try.json
CONFIG ADD kind=machine name=m1 rev=1
$ nova-config machine set m1 --width 6 --actor a1 --file try.json
CONFIG SET kind=machine name=m1 rev=2 changed=width
$ nova-config machine list --file try.json
MACHINE name=m1 user=nova seat=s1 slots=8 runners=0 width=6 tla=false note=-
CONFIG LIST kind=machine rows=1
$ nova-config machine history m1 --file try.json
HISTORY id=1 kind=machine name=m1 op=add actor=a1 at=2026-10-02T03:18:20Z note=- runners=0 seat=s1 slots=8 tla=false user=nova width=4
HISTORY id=2 kind=machine name=m1 op=set actor=a1 at=2026-10-02T03:18:20Z width=4>6
CONFIG HISTORY kind=machine name=m1 changes=2
Verbs
The nova-config section of the command reference documents every verb's flags, effect and exit codes.
helpversionkindsmigratestatusapplyinventorymachineloginlogoutfleetsprint
Spec
The contract is docs/SPEC-CONFIG.md.
Documentation
¶
Overview ¶
Command nova-config is the one tool for the fleet's permanent, non-ephemeral configuration: it owns Postgres (schema `config`, its migrations, its history) and every registry of the fleet, and it applies that configuration into Redis so Redis is always a rebuildable copy. The runtime tools (nova-friend, nova-sprint) read configuration and never write it. The contract is docs/SPEC-CONFIG.md; the guide is docs/nova-config/README.md.
Every kind (machine, fleet, friend, sprint, loop, route) has the same six verbs -- add, remove, set, list, show, history -- generated from its descriptor in pkg/config, so every kind has identical flags, help and refusals; a singleton kind (fleet: one row the migration creates) has set, show and history without a name. apply diffs Postgres against Redis per kind and writes the difference through the runtime's own Redis Functions, compare-and-set on a revision stamped in config:decl. --file keeps the rows in a local JSON file in Postgres's place (config.FileStore), so every verb but apply's write runs with no database.
Exit 0 done, 1 refused (the store or Redis said no: a duplicate, a missing row, a ceiling, a conflict), 2 usage (could not run: a flag, a store that did not answer), plus two for machine self: 2 when --check finds the name is no machine row, and 3 when the name or the rows could not be read. A refusal is one stderr line, `nova-config <verb> REFUSED: <what>; run: <next>`.
Source Files