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 runtime or target artifact being inspected,
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.

Select the configuration key through its protected file path before running the following examples:

bash

export NUCLEUS_KEY_FILE=/data/nucleus-key

Check the supplied binary

The Workspace server image provides numin at /bin/numin. DEB, RPM, and the server archive also include the matching binary. Always use the tool from the same runtime or target artifact.

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`.
A product update remains in the maintenance gate	Inspect it read-only with `numin product-release status --json`.
You plan a first installation or update	Inspect the target artifact, backup, and schema transition with `numin deployment plan`.
A historical 7.30 source state still binds `System Root` to `System Owner`	Before the target-binary Doctor, inspect it with `numin iam system-root-role-binding --json`.
Existing data still uses historical sender fields or lacks an explicit Commerce default sender	Stop the runtime and use `numin sender-profiles legacy-cutover`.
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`.
A documented historical recovery case concerns Taskstream producer sources	Run `numin taskstream producer-sources status --json`; routine product updates create missing sources automatically.
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 migrations preflight --json
numin --config /data/nucleus.config.enc schema drift --json

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

schema migrations status --json also reports invalid fulfillment_follow_up_mode_contract values under preflightFindings. The finding contains the total count, no more than 500 identities sorted by tenant and variant ID, and truncated. It contains no raw values and changes no data. Correct the affected product variants to manual or automatic through the tenant-bound PIM workflow, then rerun the command after each correction round. There is no --apply or direct database path for this finding.

schema migrations preflight --json also checks sender-profile revision windows before an update. The senderProfileRevisionWindow object reports the status, invalid-window count, and overlapping-pair count. It does not include tenant, profile, or revision identifiers. A blocked status prevents the schema transition. Stop the update and arrange a supported correction of the existing data before rerunning the preflight. Do not use ad-hoc SQL; this finding has no numin --apply path.

Inspect the product release

bash

numin --config /data/nucleus.config.enc product-release status --json

This command is read-only. Exit code 0 confirms the fully verified release contract. Exit code 1 reports a blocked, failed, or incomplete run. Routine updates have no matching --apply command: the official server binary applies only its build-bound safe transitions.

Inspect the historical System Root role binding

This one-time offline contract applies to 7.30 source states whose earlier bootstrap still bound the canonical System Root group to the global System Owner role. Before the protected target-binary Doctor, use numin from the exact staged target artifact:

bash

numin --config /data/nucleus.config.enc \
  iam system-root-role-binding --json

Exit code 0 with status: ready confirms that no correction is pending. Only exit code 1 with status: repair_required, checked: 1, repairable: 1, and blockers: 0 represents the exact supported historical state. Before applying the correction, stop every server and worker process, verify the restore-tested backup, and obtain explicit operational approval:

bash

numin --config /data/nucleus.config.enc \
  iam system-root-role-binding --apply --json

A blocked status, any other report, or exit code 2 leaves the installation unchanged and requires manual investigation. After a successful apply, restart the same source version, repeat the dry run, then create and restore-test a new complete backup. Only this post-repair evidence may be used by the following target-binary Doctor. Neither the release nor the server path ever applies the correction automatically.

Plan an installation or update

deployment plan combines the current database state with the build-bound contract of the staged target release. It never changes data:

bash

numin --config /data/nucleus.config.enc deployment plan \
  --artifact-digest <sha256> \
  --backup-evidence /secure/backup-evidence.json \
  --json

Use the digest of the exact target binary or OCI artifact. Backup evidence has this contract:

json

{
  "createdAt": "2026-07-31T10:00:00Z",
  "database": true,
  "storage": true,
  "config": true,
  "restoreTestedAt": "2026-07-31T10:15:00Z"
}

The file contains no password or backup content. Exit code 0 reports ready: true. Exit code 1 reports stable actions such as a missing target artifact, restore evidence, or an incompatible schema baseline. The plan accepts evidence for no more than 24 hours after createdAt; create and restore-test a new backup when activation happens later.

Inspect transitionClass, minimumRuntimeBaseline, pointOfNoReturnReached, rollbackBefore, and rollbackAfter. forward_only does not permit an old binary after the point of no return. Repair forward with the target release, or restore PostgreSQL, storage, encrypted configuration, and runtime key as one set.

Check an Emergency manifest

Use this variant only after external signature verification of an OCI manifest with stateChangeClass: runtime_only:

bash

numin --config /data/nucleus.config.enc deployment plan \
  --artifact-digest <target-digest> \
  --emergency-manifest /secure/emergency-release.json \
  --json

Continue only when ready: true, releaseMode: runtime_only, and rollbackToSource.allowed: true. numin validates the binary, manifest, and database contract. It does not establish trust in the signature of its own image. Use the separately trusted verifier under Recover from critical runtime failures safely first.

Cut historical sender profiles over

Run this cutover before you start the target release when an update of an existing installation reports historical sender data. Stop every server and worker process, verify the current backup, and use numin from the exact target artifact that you will start afterward.

Inspect the state without writing data:

bash

numin --config /data/nucleus.config.enc \
  sender-profiles legacy-cutover status --json

Exit code 1 reports required operator action. The output identifies the affected profiles, proposed sender profile IDs, and the permitted candidates for each Commerce profile. It does not expose historical sender content.

Select one listed candidate explicitly for every reported Commerce profile and write the plan to a protected path:

bash

numin --config /data/nucleus.config.enc \
  sender-profiles legacy-cutover plan \
  --commerce-default <commerce-profile-id>=<sender-profile-id> \
  --output /secure/sender-profile-cutover.plan.json

Repeat --commerce-default for multiple Commerce profiles. numin never infers the business default. Document and Notification sender data is copied conservatively into the plan. The plan expires after 15 minutes and is bound to the target binary and current database state.

Review the selection and apply that exact plan after operational approval:

bash

numin --config /data/nucleus.config.enc \
  sender-profiles legacy-cutover apply \
  --plan /secure/sender-profile-cutover.plan.json \
  --apply \
  --json

The apply operation is transactional. It writes only the planned profiles, revisions, and bindings, does not delete historical fields, and does not advance the schema baseline. An expired plan or a plan that no longer matches the state is rejected. Run status --json again. Start the target release only after it reports ready: true with exit code 0.

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 and producer sources. 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. It also reports expected, active, missing, inactive, and invalid producer sources and the Taskstream authorization revision anchors of every active tenant. Missing anchors keep complete false but can be initialized at revision 1 by the approved apply. An existing revision of 0 or less is invalid and makes applyEligible false.

An installation whose Attempt cutover is already applied can report alreadyApplied: true, an incomplete source or revision-anchor phase, and applyEligible: true; apply then adds only the incomplete phase. Stop when the result reports applyEligible: false and complete: 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, Controls, only missing catalog-bound producer sources, and only missing Taskstream authorization revision anchors. A baseline anchor grants no permission and does not replace current permission checks. The transaction invents no old execution history, never rewrites an existing revision or source, and never reactivates a tombstone. Existing jobs remain inactive and require individual review and reauthorization. During the initial cutover, the final write raises the schema contract as a downgrade fence.

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

Approve Taskstream producer sources

A new installation creates the currently cataloged internal producer sources during its first global bootstrap. An update to an existing installation can add new catalog entries. The server stays available, while only the dependent feature remains blocked.

Inspect the read-only status first:

bash

numin --config /data/nucleus.config.enc \
  taskstream producer-sources status --json

Create a plan for missing sources. The plan expires after 15 minutes:

bash

numin --config /data/nucleus.config.enc \
  taskstream producer-sources plan \
  --output /secure/path/taskstream-producer-sources.plan.json

An inactive or invalid source remains unchanged. Reapprove its exact ID only after review:

bash

numin --config /data/nucleus.config.enc \
  taskstream producer-sources plan \
  --reapprove nucleus.crm.lead.company_research \
  --output /secure/path/taskstream-producer-sources.plan.json

Review and apply that exact plan:

bash

numin --config /data/nucleus.config.enc \
  taskstream producer-sources apply \
  --plan /secure/path/taskstream-producer-sources.plan.json \
  --apply \
  --json

apply rejects an expired plan, another binary version, or a changed database or catalog state. Create a new plan in that case. Do not repair sources with SQL or a seeder. Verify the result with another status call and nucli readiness.

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.