Set up an enterprise agent¶

Goal: point a local runtime agent at your organisation's Control Plane (/api/v1) so it can sync published policy and appear on the fleet — without using the open demo surface (/api/public).

Same binary as Community

Enterprise is additive. Install and bootstrap like anyone else; then turn the portal client on with your org's API origin and (when enforced) org license key. Nothing here is required for offline Community use — see Installation.

Inputs¶

Input	Required	Where it comes from
`runtime` installed	yes	Install Runtime
Runtime Home bootstrapped	yes	`runtime bootstrap` (contracts + working state)
Control Plane API origin	yes	Shared `https://api.engineeringruntime.com` or your company `app-api`
Path prefix `/api/v1`	yes	Enterprise surface — not `/api/public`
Org API key (`erk_…`)	yes when the API enforces auth	app. → API Keys (one key per org)
Invitation to `app.`	yes for humans publishing policy / issuing keys	How to get access

Point at the API, not the UI

portal.base_url must be the API host (api.… or your app-api), never app.engineeringruntime.com or demo.engineeringruntime.com. Sync expects JSON from {base_url}{path_prefix}/policies?active=true.

Mental model (first time)¶

Install + bootstrap (local contracts)
        ↓
Admin issues ONE org license key in app. → API Keys
        ↓
On the agent (local wire — never written by portal sync):
  enable portal + base_url + path_prefix=/api/v1 + org key
        ↓
runtime portal sync  →  pull published policy (and later enterprise-*)
        ↓
Fleet / audit on app. see this agent

Stays on the agent forever	Arrives only after sync
`portal.enabled`, `base_url`, `path_prefix`, API key	Published policy (and enterprise config/context when those ship)
Set via env or a small org-managed YAML	Control Plane is the source of truth

Chicken-and-egg: the agent must already know where the Control Plane is and how to authenticate before the first sync. Those fields are never delivered by the portal itself — see Connect the Control Plane.

Commands¶

Option A — environment only (CI / Kubernetes secrets)¶

# 1. Local home (example)
export ENGINEERING_RUNTIME_HOME="${ENGINEERING_RUNTIME_HOME:-$HOME/.engineering-runtime}"
runtime bootstrap

# 2. Enterprise portal wire
export RUNTIME_PORTAL_ENABLED=true
export RUNTIME_PORTAL_BASE_URL=https://api.engineeringruntime.com
export RUNTIME_PORTAL_PATH_PREFIX=/api/v1
# When your deployment requires a key (and once the binary sends it):
# export RUNTIME_PORTAL_API_KEY=erk_…    # from vault — one org key for the fleet

# 3. Verify + sync
runtime portal status
runtime portal sync

Option B — portal-only config file¶

$RUNTIME_CONFIG_FILE loads a normal config YAML. For enterprise bootstrap it may contain only the portal: block; other keys use defaults.

# /etc/engineering-runtime/portal-bootstrap.yaml  (org-managed, outside Home)
portal:
  enabled: true
  base_url: https://api.engineeringruntime.com
  path_prefix: /api/v1

export RUNTIME_CONFIG_FILE=/etc/engineering-runtime/portal-bootstrap.yaml
# Prefer the key in the environment, not in the file:
# export RUNTIME_PORTAL_API_KEY=erk_…
runtime portal status
runtime portal sync

Full client reference: Connect the Control Plane.

Expected output¶

runtime portal status should show the portal enabled, your API base_url, and path prefix /api/v1.

runtime portal sync should complete without error and refresh the local policy the agent enforces (today: policy file written from the active publish; enterprise enterprise-* Home artifacts land with the contracts-only Home work).

After a process that heartbeats, the agent should appear under Fleet on app.engineeringruntime.com.

Failures¶

Symptom	Likely cause	What to do
Sync decode / non-JSON error	`base_url` pointed at a UI or HTML page	Use the API origin only
Wrong policy / demo data	`path_prefix` still `/api/public`	Set `/api/v1` for enterprise agents
`401` / auth rejected (when enforced)	Missing or revoked org key	Re-issue in API Keys; roll `RUNTIME_PORTAL_API_KEY` via vault
Portal disabled in `status`	`RUNTIME_PORTAL_ENABLED` unset/false or empty `base_url`	Enable and set URL
No row on Fleet	Process never heartbeated / wrong org surface	Run a command after portal is enabled; confirm `/api/v1`

What works today vs what is landing next¶

Document only what the binary and shared API actually do — see also Control Plane → What works today.

Step	Today (shared `api.`)	Target (authenticated enterprise)
Enable portal + `base_url` + `/api/v1`	Works	Same
Issue org API key in `app.`	Works (keys UI/API)	Same — one key per org, share via vault/CI
Runtime sends the key on sync/heartbeat	Not in the binary yet	`RUNTIME_PORTAL_API_KEY` / `portal.api_key`
`/api/v1` refuses callers without a credential	Shared deploy is still demo-open (`REQUIRE_AUTH` posture)	Always required for `/api/v1`

Until the runtime sends the key and the shared API enforces it, configure the enterprise path (/api/v1 + org key in secrets) now so agents are ready; do not teach /api/public as the production enterprise setup.

Live auth posture: /metadata/authentication.

Next¶

Publish or confirm an active policy in app. → Control Plane
Run a real capability; confirm audit / fleet
For client knobs and failure behaviour → Connect the Control Plane
For what is not built yet (SSO, self-serve org, …) → Roadmap