API keys & sandboxes

An API key is your OpenEng key: the credential the openeng engine starts with, and the one headless and sandbox machines use. Sandboxes are meant to register machines as a managed fleet that pulls work from your account through the Console; the current engine can't register a node yet. The two pages (Deploy → API keys, Deploy → Sandboxes) are two views of the same thing: which machines may work for your account, and which one is live.

API keys

What they are

An API key (OPENENG_KEY) is the credential the engine starts with: pass it as --key=<key> or set the OPENENG_KEY environment variable (start the engine). The engine registers the key with the platform, which checks the key and your plan and ties the key to that one running engine. The same key authenticates headless and sandbox-mode machines — the credential that lets unattended nodes pull your configs and work. Issue one per machine-job (laptop, ci-runner, nightly-box).

Issuing — and the return-once rule

Issue key opens a panel with two fields:

• Label — what the key is for (e.g. the machine it lives on).
• Scopes — optional, comma-separated; empty means full account scope. A scope has the form <resource>:<action>, such as config:read, and the server refuses anything else. Scopes are recorded but not enforced yet, so every key currently has full account authority.

The next screen shows the key value exactly once. Copy it now and set it as OPENENG_KEY on the target machine. The server stores only a hash — once the panel closes, the value can never be displayed again, only revoked and reissued. (The page drops it from memory the moment you close.) A key expires one year after it's issued.

export OPENENG_KEY="oeng_…"     # on the machine that will use it
openeng serve                    # or: openeng serve --key="oeng_…"

At your plan's key limit, Issue key is disabled and its tooltip gives the reason (for example Pro includes 1 API key — you're using 1); a meter next to it shows keys used against the limit.

Keys, engines and machines

A key authenticates, but machines are still counted (Plans & billing):

• One engine per key. The platform ties each key to one running engine. Starting a second engine with the same key fails with this key already runs an engine — stop it or generate a new key. Pro includes one key, so one engine at a time.
• Headless machines (no terminal — CI, servers) take a headless machine slot: Free 0 · Pro 1 · Enterprise unlimited, or a number set on the account. The platform counts headless runners holding a live lease; the current engine's openeng headless only checks the key and exits (headless machines).
• Sandbox mode — nodes register freely; active nodes are limited (below).

Below the key cards, Active engine sessions lists the engines signed in on your machines, with their last heartbeat.

Key cards

Each non-revoked key shows: label · mono key id · Created · Last used (an em-dash until the stamp populates) · Scopes chips (or full account) · and the Bound sandbox (or Not bound). Each card has Rebind and Revoke (Revoke asks you to confirm).

Key ↔ sandbox binding

A key can be bound to exactly one sandbox, and a sandbox to one key. Rebind picks a new node, with the consequence named before you confirm:

"node-a will stop receiving work on its next sync. This key then authorizes only node-b."

On Pro — where exactly one sandbox is active — rebinding the key is the activation selector. A node bound to a key refuses to register under any other key; an unbound node accepts any of your keys until one is bound. Revoking a key stops it from registering an engine or calling the API; the fleet page reflects it on the next sync. An engine already connected keeps its Broker session until that session expires (up to 24 hours), so stop the engine as well.

Sandboxes

What a sandbox node is

A machine that works for your account through the platform's relay instead of for a person at a keyboard: the terminal is replaced by the platform's work queue. The relay registers the node, hands it one job at a time on its sync, and records what it reports back; results go to a storage point. Only the active node receives work; inactive nodes keep syncing but never lease work.

Registering a node

Registration happens on the node; this page manages the fleet. Sandbox mode is API-key-only (no interactive auth, ever). When a node registers, the platform checks, in order — each failure is an explicit refusal, never a degraded run:

1. The key is valid, and if the node is already bound to a key, it's that key (This sandbox is bound to a different API key).
2. The account is on Pro (or Enterprise): Sandbox mode requires the Pro plan.
3. The active-node limit. A node that would exceed it is still registered, inactive, so you can activate it here.

The same machine re-registering keeps its node id, activation state and key binding. A one-machine Pro fleet doesn't stall: its first node becomes active automatically when no other node is.

The fleet table

Columns: Node · Active · Status (online means seen within the last 5 minutes) · Last seen · Bound key · Config · Alloc (c/g/m) · Version. A meter at the top shows active nodes against your limit. Expanding a row opens the node detail:

• Capability profile — the hardware/models/capabilities document the node reported ("Reported at next sync" until it has).
• Resource allocation — CPU/GPU/Memory %, each clamped 1–100 (zero would deadlock job admission). Saved allocations apply at the next run boundary, never mid-run.
• Run history — the relay's run records for this node (state, timestamps, consumed tokens where reported).
• Revoke — the node gets a refusal on its next sync and shuts down.

Below the table, Active headless runners lists the headless machines holding a live lease, with their last heartbeat.

The one-active rule (Pro)

Pro registers any number of nodes but exactly one is active — only the active node receives work. The Active toggle handles the swap explicitly: activating node B while A is active raises a confirmation naming A ("stops receiving work on its next sync") and rebinding your key to B. The server enforces the swap regardless of what the UI shows. Enterprise activates any number of nodes with a plain toggle, unless a size is set on the account.

If a fleet exists and no node is active, the page shows a choose one banner — until you pick, the fleet receives no work. Activation requires an API key to bind: with none issued, the toggle stops with Issue an API key first and points you to the API keys page.

Plan & tier notes

An Enterprise account can also have its own sizes set for keys, active sandboxes and headless machines. Both pages show locked states on Free, with meters (e.g. Active 1/1) once unlocked. The server enforces every limit independently of the UI. Because an API key needs Pro, so does running the engine; Pro and Enterprise launch in Q4 2026 and can't be purchased yet (Plans & billing).

Troubleshooting

Lost the key value. Unrecoverable by design (only the hash is stored). Revoke the key and issue a new one — two clicks.

this key already runs an engine — stop it or generate a new key. Another engine is running with this key. Stop it, or issue a second key (Enterprise) for the second machine.

cannot start: no OpenEng key. The engine found neither --key nor OPENENG_KEY. Export the key in the shell that starts the engine.

The node never appears on the Sandboxes page. Expected with the current engine build, which doesn't register sandbox nodes (see the warning under Sandboxes).

The node is online but receives no work (once sandbox mode ships). On Pro, is it the active node? Is your key bound to it (rebinding elsewhere cuts it off on next sync)? Is the queue actually non-empty?

"Issue an API key first" when activating. Activation binds your key to the node — issue a key on the API keys page, then activate.

Allocation changes don't seem to apply. They apply at the next run boundary, never mid-run. Values are clamped to 1–100 on save.

Revoked a node but it still shows online. Status updates on the node's next sync — at which point it receives its cut-off and stops.