Skip to content

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 ENGRT_PORTAL_ENABLED=true
export ENGRT_PORTAL_BASE_URL=https://customer-control-plane.example
export ENGRT_PORTAL_PATH_PREFIX=/api/v1
export ENGRT_PORTAL_API_KEY='<show-once-runtime-key>'
engrt 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

engrt portal register
engrt 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, ENGRT_CONFIG_FILE, ENGRT_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

engrt 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 ENGRT_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 engrt 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.14.0. After bootstrap, the version-exact files in Runtime Home win.