Install Nookins

Before you begin

Use Linux x86_64 with glibc 2.39+, a terminal, and a new home directory. The current public installer does not establish support for macOS, native Windows, or a public OCI distribution. Provider access and sign-in are separate; downloading Nookins does not include model access.

Check your system:

uname -m
ldd --version

Expect x86_64 and glibc 2.39 or later. Do not use the installer on an unsupported system just because the script downloads successfully.

Download and install

Public alpha 0.54.1-alpha.1 · Linux x86_64 · glibc 2.39+

export NOOKINS_HOME="$HOME/.nookins"
curl -fsS https://nookins.app/install.sh -o install-nookins.sh
# Review the downloaded script before running it.
bash install-nookins.sh --home "$NOOKINS_HOME"

The default home is ~/.nookins. It must not exist yet for a fresh install. If you already have a Nookins home, follow the update guide.

The NOOKINS_HOME variable in these guides selects the installation you mean to use. Keep the same value in every terminal. Use ~/.nookins for a new installation. If it already contains a Nookins home, follow the update guide. Do not remove ownership records to bypass an installer refusal.

For inspection: install script · release archive · SHA-256 checksum.

The initial installer is trusted through HTTPS. Checksums detect file changes; the installer verifies the signed release feed before installing the runtime, and updates use that release trust. A successful download alone is not a completed installation.

The current application installer includes defaults, the operator interface, and documentation. Workspace tools are downloaded when enabled execution or document tools need them, then reused across updates. The installer leaves the service stopped for onboarding.

Initialize a text-only trial

After installation succeeds:

"$NOOKINS_HOME/bin/nookins" --version
"$NOOKINS_HOME/bin/nookins" onboard --no-tui --sentinel not-now

This initializes configuration without starting the service or signing in. Keep all messaging accounts disabled in config/channels.yaml. In config/nookins.yaml, set speech.text_to_speech: disabled for a text-only trial. Keep Sentinel disabled until you choose its attention behavior.

Leave generated keys in secrets.env intact; Nookins reads that file itself. Do not post it in a support report.

With the service still stopped, validate and review the configuration before applying it:

"$NOOKINS_HOME/bin/nookins" config validate
"$NOOKINS_HOME/bin/nookins" config apply --offline --dry-run
"$NOOKINS_HOME/bin/nookins" config apply --offline

Confirm the intended agents and disabled messaging accounts in the dry run before applying.

Next: your first reply

Install the managed Codex client, sign in, and talk to your Nookin locally.

If installation refuses or is interrupted, preserve the command output and operation files. Follow the reported recovery instructions before retrying. Troubleshooting explains what to collect.

Repair missing update settings

Use the single repair script for an existing Nookins installation with missing update settings, or for a supported older alpha that needs the 0.47 transition. It detects your installed version automatically. Python 3.10 or newer is required; the older-version upgrade requires Linux x86_64 with glibc 2.39+.

On supported pre-0.47 alphas, this command upgrades the installation to 0.47.0-alpha.2 and may restart its service. The previous home is preserved at .pre-0.47. On 0.47 or newer, it restores missing update settings and checks the signed feed without installing another version or restarting the service.

Select your existing Nookins home, download the script, and inspect it before running:

export NOOKINS_HOME="$HOME/.nookins"
curl --fail --show-error --proto '=https' --tlsv1.2 \
  https://nookins.app/repair-updates.py -o repair-updates.py
less repair-updates.py
python3 repair-updates.py --home "$NOOKINS_HOME"

The same file contains the reviewed one-time bridge, including its pinned archive and root identities. You do not need to choose or download a second repair script. Supported older sources are the bridge's explicit public-alpha allowlist from 0.40.0-alpha.1 through 0.46.0-alpha.1; unlisted versions are refused before an upgrade starts.

After any required transition, the script preserves existing trust and recovery history, restores missing update settings and asks the installed verifier for the latest compatible signed alpha. If a prior installation's trust is retained in .pre-0.47, the script reports that directory as still in use; keep it. When no prior trust or recovery records remain, initialization uses the reviewed public root pin. Do not delete trust or recovery records to force a fresh start.

The script also restores missing empty config/automations.d, config/mcp.d and config/hooks.d directories. Older installations can run without these optional directories, but the 0.47 updater requires them. Existing configuration files and pending update records are preserved. A successful feed check verifies release availability; installation compatibility is checked when applying the update. If an update is already pending, the printed command resumes it.

If interrupted, rerun the same command. It resumes the recorded bridge even if the home-directory swap was interrupted, then continues settings repair. A concurrent repair is refused. Conflicting settings, ambiguous trust and unrelated recovery state are preserved for diagnosis; an explicit --trust-store /absolute/path/to/existing/trust can select a known retained store.

After the signed check succeeds, install any further available update with:

"$NOOKINS_HOME/bin/nookins" --home "$NOOKINS_HOME" update