Configure your Nookins

One home, one configuration bundle

NOOKINS_HOME selects your installation. Configuration lives below its config/ directory; private keys and provider secret values belong in secrets.env, outside YAML. Keep this home private and out of Git. Do not source secrets.env into a shell.

The four singleton YAML files and at least one agent are required. Optional resource directories can be absent. Each resource file contains its body directly: its filename is the ID. Do not wrap automations.d/example.yaml in an automations: map, or mcp.d/catalog.yaml in mcp.servers.

Resource IDs use 1–64 ASCII letters, digits, _ or - and start with a letter or digit. Unknown fields, duplicate keys, YAML anchors/aliases/merge keys/tags, multi-document YAML, .yml fragments and config.d overlays are rejected.

Choose the right level

Use agents for a role and its permissions, configuration reference for exact current fields and model providers for provider setup. Adding a route determines where a Nookin can respond; it does not grant tools. Adding a secret reference does not create or authorize an account.

Start with generated defaults rather than assembling every file from scratch. Examples with placeholder domains, phone numbers and package IDs must be adapted before activation. Exactly one agent must be primary when there is more than one; only that agent may have administration.

Activate changes

For a stopped local installation:

nookins config validate
nookins config apply --offline --dry-run
nookins config apply --offline

A dry run previews the change without applying it. Review the selected home, agent count, routes, links and grants. Resolve errors before applying. Offline apply refuses a home owned by a running foreground supervisor.

For an already-running native Nookins service, use its authenticated control interface:

nookins config status
nookins config diff
nookins config apply --dry-run
nookins config apply

Apply can restart a managed service when required. --no-restart leaves restart-required changes pending; it does not make them effective in the old process. Check status after activation. Changing the listening address requires a restart and a matching --url afterward.

Inspect and recover

nookins config revisions
nookins config export --view sanitized
nookins config explain /harness/scheduler/tick

A sanitized export is the default; still review it before sharing. Exact exports may contain private configuration. nookins config rollback reactivates a prior revision; inspect its arguments and status first. Rollback of configuration does not undo external messages or tasks already accepted.

Native schema upgrades

The documented release uses schema 19. Native configuration from schemas 8–18 requires the explicit migration path; preview with nookins config migrate, stop Nookins, then use nookins config migrate --write. Preserve the protected predecessor and the reported migration ID. --restore ID restores that protected predecessor while stopped. Check the exact migration options before recovery.

This upgrades a supported native configuration bundle. It is not a Ward home/database converter. Move from Ward explains the separate procedure.