Docs menu

Reference

The operator side

For people running a CLI platform: the Operations page, the two-person rule, passkeys, break glass, tripwires and rotating the master key.

Explain it

This page is for the people who run a CLI platform (operators), not for people hosting apps on one.

Operators see Operations in the dashboard sidebar. It's organised by job: Overview (how the platform is doing), People (find any account), Security, Money (payouts waiting for review), Moderation (listings and abuse reports), and Platform (servers, backups, drills and the status page). Each operator sees only the parts their role covers.

The most sensitive actions need two people: one operator asks, a second approves on the Operations page. That covers adding operators, approving withdrawals and adding large amounts of credit. Operators must sign in with a passkey, and operator pages only open from the networks you allow.

In an emergency, an admin can pause builds or new sign-ups for everyone, or sign everyone out and cancel every key at once ("break glass").

Planted fake secrets ("tripwires") raise an alarm if anyone ever uses one, and CLI tokens published on GitHub by mistake are cancelled automatically.

Roles and access

Operators are listed in CLI_OPERATORS (admins) or given a role: support, finance or admin (see /docs/compliance). GET /v1/me carries operatorRole. Operator routes can be limited to networks with CLI_ADMIN_ALLOW_IPS, and CLI_REQUIRE_OPERATOR_PASSKEY=1 makes a passkey (not just an authenticator code) the way operators confirm it's them.

The Operations page reads GET /v1/admin/stats, GET /v1/admin/people?q= and GET /v1/admin/people/:principal, plus the routes for each tab (cluster, backups, abuse, listings, payouts, platform health).

The two-person rule

Adding operators, approving withdrawals and manual credit over the limit answer 403 OPERATOR_APPROVAL_REQUIRED with error.details.approvalId. A second operator who covers that area approves it:

API
GET /v1/admin/approvals
POST /v1/admin/approvals/:id {"decision": "approve"}   // or "decline"

Then the first operator sends the same request again with X-CLI-Operator-Approval: <approvalId>. It works once, within an hour, for the exact same request body. An operator can't approve their own request.

Break glass

API
PUT /v1/admin/emergency {"buildsPaused": true, "signupsPaused": true, "reason": "…"}
POST /v1/admin/emergency/revoke {"sessions": true, "oauth": true, "apiKeys": true, "github": true, "reason": "…", "confirm": "REVOKE"}

Paused actions fail with PAUSED_BY_OPERATOR (503). Revoke ends every session, connected-app token, API key and GitHub link at once (pick any of them). The runbook is deploy/SECURITY.md.

Tripwires and leaked tokens

Honeytokens planted where an attacker would look alert every operator and open a critical security incident when used. Outside canary tokens can be added with CLI_TRIPWIRE_VALUES (NAME=value, one per line). GitHub's secret scanning partner program posts published CLI tokens to POST /v1/github/secret-scanning, and CLI revokes them and tells the owner.

Rotating the master key

CLI_SECRET_KEY can be replaced while running. Put the old key in CLI_SECRET_KEY_PREVIOUS, restart with the new one, and the leader re-seals everything onto it in the background:

API
GET /v1/admin/master-key
POST /v1/admin/master-key/reseal

CLI_DERIVATION_KEY decides whether tokens customers can see (webhook URLs, inbox tokens) change when the master key does. Remove the previous key once done is true.

For the rest of running a platform, see Running CLI yourself and Staging and launch checks.