Set up an Enterprise Runtime¶

Goal: convert one existing local Runtime Home into a sticky Enterprise-managed installation without changing command/capability execution.

1. Create a Runtime key¶

Sign in to the company app-ui as an administrator. In API Keys, create one key for this Runtime and copy the plaintext immediately. app-api never shows it again and stores only a peppered verifier.

Keep the key in the machine's secret/process environment. Do not put it in config.yaml, source control, command output, or audit records.

2. Configure the Portal client¶

export RUNTIME_PORTAL_ENABLED=true
export RUNTIME_PORTAL_BASE_URL=https://customer-control-plane.example
export RUNTIME_PORTAL_PATH_PREFIX=/api/v1
export RUNTIME_PORTAL_API_KEY='<show-once-runtime-key>'
runtime portal status

The base URL is the company's app-api deployment, not the public API reference site. /api/v1 is the only accepted prefix.

3. Register once¶

runtime portal register
runtime portal status

Registration binds the key to this stable installation identity. Runtime pins the returned organization and Ed25519 public signing key only after verifying a fresh-nonce signed receipt for the exact Control Plane origin and identities, verifies and atomically installs the first policy/config generation, then records sticky Enterprise-managed state. If any step fails, local authority remains unchanged.

After registration, RUNTIME_CONFIG_FILE, RUNTIME_POLICY_FILE, Runtime Home local files, and disabling Portal networking cannot override or undo Enterprise authority. The last verified managed generation is used offline. Missing, edited, substituted or rolled-back managed state fails closed. Governance generations do not expire in this initial contract; they remain active until a newer verified monotonic generation is installed.

4. Refresh published governance manually¶

runtime portal sync

Policy and configuration may be edited/published independently in app-ui, but Runtime receives one signed atomic pair. Sync never downloads credentials, context, commands, or executable content. An unchanged generation returns no documents and performs no install. Capability source locations are managed configuration; Runtime still never fetches capability content.

Key recovery¶

For a normal key incident, an administrator creates a replacement bound to the same Runtime. Set the new RUNTIME_PORTAL_API_KEY; its first heartbeat or sync activates it and revokes the predecessor without changing policy/config or trust.

After an ephemeral demo database reset, create a new unclaimed key and run runtime portal register again. Recovery succeeds only when the organization and already-pinned signing key match. A key cannot replace signing trust.

Audit¶

Runtime audit stays local. Portal keys are never used for audit delivery. A future optional OpenTelemetry exporter will use its own exporter credentials and destination.

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.