Update Nookins

Before the update

Select the actual existing Nookins home. Keep your normal backup and note your agent names. Stop the foreground process with Ctrl-C, or stop the installed service using its normal service procedure. Keep the existing updater settings and recovery files in place until the update succeeds.

This procedure updates an existing Nookins installation and preserves its configuration and state.

Upgrading from 0.46 to 0.47 (one-time bridge)

The 0.47 release retired the automatic skill-evolution subsystem and moved its database and configuration forward. The updater shipped inside 0.46 cannot apply that change to itself, so a 0.46 home cannot reach 0.47 with nookins update. Use the one-time bridge instead:

export NOOKINS_HOME="$HOME/.nookins" # Your existing 0.46 Nookins home.
# Stop Nookins first (Ctrl-C in the foreground, or your service stop procedure).
curl -fsS https://nookins.app/update-to-0.47.sh -o update-to-0.47.sh
# Review the downloaded script before running it.
bash update-to-0.47.sh --home "$NOOKINS_HOME"

The bridge builds a fresh 0.47 home from your running 0.46 home, migrates the configuration and database forward, carries your agents, artifacts, provisioned runtime assets, messaging channel sessions and provider credentials, then swaps the upgraded home into place atomically. Your original home is kept alongside it until you confirm the upgrade, and the bridge rolls back on any failure. It is idempotent: if it is interrupted, re-run the same command.

After 0.47 you are back on the normal nookins update path below; the bridge is a one-time step and is not needed again.

Check and update

export NOOKINS_HOME="$HOME/.nookins" # Your existing Nookins home.
"$NOOKINS_HOME/bin/nookins" --version
"$NOOKINS_HOME/bin/nookins" update --check
"$NOOKINS_HOME/bin/nookins" update
"$NOOKINS_HOME/bin/nookins" --version

The check inspects the selected signed release feed; it does not install an update. Confirm the installed version before proceeding.

Rescue an older updater or reinstall

If an older updater reports update_installed_identity_unqualified, or the installed binary cannot run, use the current rescue script. It downloads a pinned current updater and applies the signed release to the existing home without executing the old launcher:

export NOOKINS_HOME="$HOME/.nookins" # Your existing home.
# Stop the old service using its normal service procedure first.
curl -fsS https://nookins.app/rescue-update.py -o rescue-update.py
# Review the downloaded script before running it.
python3 rescue-update.py --home "$NOOKINS_HOME"

This requires Linux x86_64, Python 3.9+ and glibc 2.39+. It preserves user data, credentials and existing publisher trust. It retains downloaded inputs and prints an exact retry command. Use --settings /absolute/path/update.json when you need to select an existing custom trust store or operation directory.

From 0.57, normal updates accept stopped copied or restored homes and missing old install receipts. The target must still be authenticated and support the actual current database and configuration. update --check works independently of runtime admission, including while the service or an update is busy; an unknown installed version is reported as unknown.

Use nookins update --force to reinstall the selected signed release. Add --version VERSION for an explicit supported target. Force never skips signatures, data compatibility or writer exclusion. Downgrade targets must implement the 0.57 update protocol; earlier versions are refused. An unknown old executable is retained but cannot qualify an automatic restart after failure.

An interrupted active transaction still needs its recorded recovery. Preserve its files; a damaged active journal or multiple different database snapshots needs specific recovery, rather than deleting a fence and guessing which data to use.

Consolidate maintenance files

For the 0.41.1-alpha.1 layout and later, use the newly installed binary while Nookins is still stopped:

"$NOOKINS_HOME/bin/nookins" --home "$NOOKINS_HOME" maintenance consolidate
"$NOOKINS_HOME/bin/nookins" update --check
"$NOOKINS_HOME/bin/nookins" update

The public installer consolidates automatically. Existing 0.40/0.41 homes use their retained updater settings for the update, then consolidation moves maintenance records into $NOOKINS_HOME/maintenance. A repeated consolidation resumes or reports no work. Older full-bundle cache may remain.

If interrupted, preserve all remaining paths and repeat the same command. Busy or unfinished operations, custom paths, and collisions require resolving the reported problem first. Do not manually move or delete sibling files after a refusal. Retain the old generation and maintenance records for recovery.

Verify your Nookins

The final check and update should report up to date. Confirm your configuration and selected agents remain, then start Nookins normally. Workspace tools may take longer to prepare on the first start if enabled.

Repeat the local reply check and your one-conversation check. Provider login, real replies, and messaging are hands-on checks, not established by updater success alone.

Missing update configuration

If the updater cannot read maintenance/update.json, see repair missing update settings. The same downloadable script detects the installed version: supported pre-0.47 alphas run the embedded one-time bridge, then missing settings and empty optional configuration directories are restored and the latest signed release is checked. Existing configuration files, trust and recovery records are preserved. On older versions the transition may restart the service; on 0.47+ repair does not apply the update. The 0.47 updater can also report a data-compatibility refusal when config/automations.d, config/mcp.d or config/hooks.d is absent; the repair script restores those empty directories before you resume the pending update. Other compatibility refusals still require diagnosis; a successful feed check does not prove an update can be installed.