Ephemeral Realms

Ephemeral Realms

Since 0.14.0 a realm is created in one of two forms:

	Permanent (default)	Ephemeral (disposable)
Created by	add_realm / POST /api/realms	same, plus ephemeral: true and an optional ttl
Lives until	explicit remove_realm	its expiry lapses (or explicit removal)
Survives restart	yes	yes, up to its expiry — expires_at is persisted
Use for	organizations, long-lived integrations	CI runs, test suites, demos, per-session or per-job isolation

When an ephemeral realm expires, disposal is complete: realm config, every token scoped to the realm, runtime producers/consumers/subscriptions, connected sockets (force-disconnected), and all durable messages and dead-letter entries in storage. Expiries are checked once a minute and at server startup, so a realm disappears at most ~60 s after expires_at.

Rule of thumb: if your workload creates realms programmatically and would otherwise need cleanup code, create them ephemeral.

Creating one

{ "command": "add_realm", "realm": "ci:run-4821", "ephemeral": true, "ttl": "2h" }

• ttl accepts "250ms", "90s", "15m", "2h", "7d", or a bare number of seconds. A ttl alone implies ephemeral: true.
• Without a ttl the default lifetime is 1 day (auth.ephemeral_realm_ttl to change).
• temporary / disposable are accepted as input aliases.
• The HTTP provisioning endpoint takes the same fields and reports ephemeral + expires_at (epoch ms) — see Observability HTTP API.
• Both manager tools expose it: the CLI asks "Ephemeral (disposable) realm?", the web UI has an Ephemeral checkbox + TTL field and shows an ephemeral · expires … pill per realm — see Manager Tools.

Managing the lifetime

{ "command": "set_realm_lifetime", "realm": "ci:run-4821", "ephemeral": true, "ttl": "4h" }
{ "command": "set_realm_lifetime", "realm": "ci:run-4821", "ephemeral": false }

• A new ttl resets the expiry to now + ttl — the heartbeat pattern: a long-running job re-issues the ttl periodically and the realm lives exactly as long as the job does.
• ephemeral: false converts to permanent (clears the expiry); ephemeral: true converts a permanent realm to disposable.
• The structural default and * realms are always permanent.
• remove_realm performs the same full disposal immediately, for either form.

What callers must handle

• Expiry is a hard stop — sockets are force-disconnected and reconnection fails auth (realm and tokens are gone). Treat disconnect + AUTH_FAIL as "realm expired", not a transient error.
• Durable data dies with the realm — drain the DLQ before expiry if you need it.
• Name realms uniquely per run (ci:run-<id>, session:<uuid>) — add_realm returns 409 on collision.
• The sweep has up to 60 s of slack — don't assume disposal is instant.

The full implementation guide for services and agents that provision ephemeral realms programmatically (creation paths, token minting, failure modes) is EPHEMERAL-REALMS.md in the repo.