numin for local offline administration

numin is the local maintenance tool for operators of a self-hosted Workspace installation. Use it for supported pre-start, database, or recovery tasks that require the server to be offline. Use nucli for tenant-bound work against a running server.

numin has no remote login and opens no listener. It does not bypass the authentication, permissions, or tenant rules of a running server.

Prerequisites

Run numin only in an approved privileged environment. You need:

the same numin version as the Workspace server,
access to the encrypted server configuration and its configuration key,
a local connection to the Workspace PostgreSQL database,
storage-root access for site contract upgrades,
a current backup and documented approval before a write operation.

Never place configuration keys, database passwords, or new administrator passwords in logs, tickets, or command arguments.

Check the supplied binary

The Workspace server image provides numin at /bin/numin. Use the binary from the same server image or the matching Nix package.

bash

/bin/numin version

Choose the correct command

Situation	Action
The server is running and you inspect tenants or resources	Use `nucli`.
Startup is blocked by a schema contract or baseline finding	Inspect it with `numin schema`.
Inventory ledger aggregates need verification	Run `numin inventory reconcile` without `--apply`.
A local site source contract needs an upgrade	Run `numin site upgrade-contract` without `--apply` first.
You are preparing the documented Taskstream attempt cutover	Freeze the old runtime and run `numin taskstream attempt-cutover` without `--apply`.
The initial system administrator password is lost	Use the explicit stdin password reset.
No documented command covers the task	Stop. Do not invent a direct database repair.

Inspect schema and baseline state

bash

numin --config /data/nucleus.config.enc schema status --json
numin --config /data/nucleus.config.enc schema migrations status --json
numin --config /data/nucleus.config.enc schema drift --json

These commands are read-only. Do not repair drift with ad-hoc SQL.

Reconcile the inventory projection

Start with a read-only inspection:

bash

numin --config /data/nucleus.config.enc inventory reconcile --json

Apply the projection rebuild only after review and approval:

bash

numin --config /data/nucleus.config.enc inventory reconcile --apply --json

The command rebuilds aggregates and does not alter ledger entries. The task is complete when a subsequent dry run reports no findings.

Upgrade a site contract

Inspect the plan first:

bash

numin --config /data/nucleus.config.enc site upgrade-contract \
  --site <site-uuid> \
  --target 2 \
  --json

Add --apply only after you reviewed and approved the plan. Continue to use nucli for normal site inspection, builds, and publication.

Cut Taskstream over to persisted attempts

Use this command only for the documented offline cutover to persisted Taskstream delivery. Stop all old server, scheduler, and worker processes and revoke their database access before you continue.

Inspect the frozen database:

bash

numin --config /data/nucleus.config.enc taskstream attempt-cutover --json

The plan is eligible only when the source schema contract matches, no job is queued or running, no Control, Occurrence, or Attempt history exists, and jobs sharing a tenant-local concurrency key agree on the limit. Stop when the result reports eligible: false. Do not add this apply command to automated deployment steps.

After documented operational approval, apply the cutover:

bash

numin --config /data/nucleus.config.enc taskstream attempt-cutover \
  --apply \
  --json

The transaction creates the technical schema and Controls but invents no old execution history. Existing jobs remain inactive and require individual review and reauthorization. The final write raises the schema contract as a downgrade fence.

The cutover is complete when another dry run reports alreadyApplied: true and only compatible new server binaries use a new database credential generation. Never start an old binary after --apply. Rollback requires another freeze and a forward-compatible corrected binary; do not delete the new tables or Controls.

Reset the initial system administrator password

Pass the password only through stdin:

bash

read -rsp 'Enter the new password > ' NEW_PASSWORD
printf '%s\n' "$NEW_PASSWORD" \
  | numin --config /data/nucleus.config.enc admin reset-password \
      --password-stdin \
      --email admin@system.nucleus
unset NEW_PASSWORD

Interpret exit codes

Exit code	Meaning
`0`	The command succeeded and a check found no required action.
`1`	The check succeeded and found required operator action.
`2`	Invocation, configuration, connection, or execution failed.

Treat exit code 1 as a finding, not as a connection failure.

Next steps

Use nucli for authenticated remote administration.
Use Blob v2 key inventory to understand the local Blob v2 root-key inventory. Do not invent an undocumented numin command.
Plan a compatible server restart after approved offline maintenance.
Keep the dry-run and approval evidence with your operational change record.