Docs menu

Operate

Teams and security

Add people to a project, protect risky actions with a second factor, and understand how CLI keeps your apps, secrets and history safe.

Explain it

A project can have several people and agents, each with a role that says what they can do. CLI protects risky actions with a second sign-in step, keeps a record of every change, and keeps each project's apps sealed off from everyone else's.

How to do it: add people in the project's Settings under Team, with a role. Turn on an authenticator app or a passkey under Account settings to protect your account. You can see and end your signed-in sessions there too.

For notices about new sign-ins and other account alerts, see Your account and security notices.

A project can have several people and agents, each with a role. This page covers adding and removing members, second factors and step-up confirmation (and links to access reviews and the rule requiring a second factor), how browser sessions are protected and how to see and end them, how secrets are protected, how apps are isolated, the audit log and its on-chain receipts, and what happens if a project is held for review.

Members and roles

RoleCan
viewerRead everything (logs, usage, settings); change nothing
developerDeploy, configure, add databases, domains, backups and cron jobs
agentA developer with a spending limit, subject to the project's rules for agents
adminAlso manage members, project settings and rules, and delete data
ownerEverything; can't be removed; the only one who can withdraw earnings or delete the whole project

Reads need viewer, changes need developer, and members, settings and deleting data need admin. When a role is too low, CLI answers FORBIDDEN with details.required naming the role needed.

Only the owner can make someone an admin, or change or remove an admin. Admins manage everyone below them. Anyone can leave a project.

Environments share their parent project's people, so a member of production is a member of staging too.

Invite someone

You can add a person by email, by GitHub username, or by wallet address. People added by email get an invitation email and sign in with that address. Without a role, a wallet (or anyone given a spending cap) is added as an agent, and everyone else as a developer.

In the dashboard: open the project's members and invite by email, GitHub username or wallet.

From your terminal:

Terminal
cli members                                  # who has access
cli members add [email protected] --role developer
cli members rm [email protected]

Ask your agent:

"Add [email protected] to this project as a viewer."

Agents use cli_add_member (email or GitHub username, with a role) and cli_add_agent (another agent's wallet, with a spending cap in USDC). Both need an admin.

With the API:

API
POST /v1/projects/:id/members
{"email": "[email protected]", "role": "developer"}

Send "github": "<username>" or "wallet": "0x…" instead of email, and optionally "spendCap" in micro-USDC. Change a member with PATCH /v1/projects/:id/members/:principal and remove one with DELETE /v1/projects/:id/members/:principal.

Review who has access

Owners and admins can run an access review: a recorded check, on a schedule if you like, that every person and API key with access still needs it. Removing someone in a review takes effect at once. See Access reviews and 2FA rules.

Agents and keys

Agents usually connect with a project key rather than as a member. Keys have their own role, scopes, spending cap, expiry, IP allowlist and optional list of services. See Agent permissions and limits. To cut off every agent at once, revoke every key and agent member in one call:

Terminal
cli keys revoke-all

Second factor

People can add an authenticator app and passkeys under Account security in the dashboard. API keys don't have second factors; only signed-in people do.

Add an authenticator app

  1. Start setup. CLI returns the secret for your authenticator app.
  2. Enter the current 6-digit code to turn it on.
  3. Save the recovery codes CLI shows you. Each works once if you lose your authenticator.

With the API:

API
POST /v1/me/2fa/totp
POST /v1/me/2fa/totp/enable
{"code": "123456"}

GET /v1/me/2fa shows what you have set up, and DELETE /v1/me/2fa/totp removes the authenticator.

Add a passkey

With the API:

API
POST /v1/me/passkeys/options
POST /v1/me/passkeys
{"response": {…}, "name": "Laptop"}

DELETE /v1/me/passkeys/:id removes one.

Require a second factor

An owner can require everyone who changes anything in the project to have a second factor. People without one can still view everything their role allows, but changes answer MFA_REQUIRED until they set one up. API keys aren't affected. See Access reviews and 2FA rules.

Step-up for risky actions

Once you have a second factor, these actions ask for it again:

  • revealing secret values or database connection URLs
  • exec in a container and SQL queries
  • approving an agent's request, applying proposals and changes
  • creating or revoking keys, and managed signers
  • withdrawals, revenue splits, rotating the project key, deleting data, deleting a project or environment, and deleting your account

A confirmation lasts 10 minutes for that session. Five wrong answers lock the factor for 15 minutes (MFA_LOCKED).

When an action needs a fresh confirmation, CLI answers STEP_UP_REQUIRED with retry after_step_up. The dashboard asks for your code or passkey and resends the request. An agent that sees this should tell you what it was doing and wait until you've confirmed in the dashboard.

With the API:

API
GET /v1/auth/step-up
POST /v1/auth/step-up
{"code": "123456"}

Send "recoveryCode" or "passkey" instead of code if you prefer. The answer says when the confirmation runs out (elevatedUntil).

Sessions in plain terms

  • In the browser, your session lives in a cookie that page scripts can't read. Your token never appears in a URL or in browser storage.
  • Changes from the browser also carry a second value in the X-CLI-CSRF header, which a different site can't know. A request without it is refused with CSRF_INVALID. This stops another site from making changes as you.
  • Agents, scripts and the cli command send a token in the Authorization: Bearer … header instead of using cookies.
  • Every session lasts 24 hours at most, however you signed in.
  • Idle sessions end sooner if the server's operator sets an idle timeout (CLI_SESSION_IDLE_MINUTES, see /docs/self-hosting). A session unused for longer than that is ended, and the next request answers UNAUTHORIZED ("Signed out after being idle"). Sign in again. A session counts as used whenever it makes a request; CLI notes this at most once a minute.

See where you're signed in

In the dashboard: your Account page has Where you're signed in: each session, when it signed in, when it was last used and when it ends, with This browser marking the one you're using. It also says how long sessions last on this server, including the idle timeout if there is one.

With the API:

API
GET /v1/me/sessions
JSON
{
  "sessions": [
    { "id": "3f9a0c1d2e4b", "current": true, "createdAt": 1767225600000, "lastUsedAt": 1767229200000, "expiresAt": 1767312000000 }
  ],
  "idleMinutes": 120
}

id is a short label, not the token. idleMinutes is 0 when there's no idle timeout.

Sign out everywhere

If you've lost a laptop or signed in somewhere you shouldn't have, end every other session at once.

In the dashboard: under Where you're signed in, click Sign out everywhere else. It appears when you have more than one session.

With the API:

API
POST /v1/me/sessions/revoke-all
{"keepThisSession": true}

The answer says how many sessions ended (signedOut). The session making the request is kept unless you send "keepThisSession": false. Both routes need a person; API keys get FORBIDDEN, and are revoked separately (see /docs/agent-permissions).

Deleting a project or your account

An owner can delete a whole project, with 7 days to restore it, and you can delete your own account once you own no live projects. See Deleting projects and accounts.

Isolation

  • Every app, database and sandbox runs under gVisor, a sandboxed kernel, with CPU, memory and process limits and no extra capabilities.
  • Each project has its own private network. Databases live only there, so other projects can't reach them.
  • The API itself has no access to Docker. It talks to a separate worker process over signed requests, and builds can run on separate machines.
  • Images are pulled with throwaway credentials and pinned to their digest. Rollbacks refuse any other image. Images can optionally be scanned with Trivy.

Secrets handling

  • Variable values are write-only and secret by default. Reading them back needs the secrets scope on a key, or step-up for a person.
  • Each project's secrets are sealed with the project's own key, which is wrapped by a key management service in production. Admins can rotate the project key, which re-encrypts everything.
  • Secret values are masked in logs and log drains.
  • Every read of secret values or connection URLs is recorded in the audit log.
  • Code uploaded with cli up is scanned first. An .env file, a private key or a live API key stops the upload with SECRETS_IN_UPLOAD, listing files and lines but never the values.

See Buckets, queues and secrets for syncing secrets from Doppler or Vault and rotating them on a schedule.

Audit log

Every successful change is recorded: who made it, what changed, and when. Variable changes are recorded by name only, never values. Entries are kept for 90 days, unless the server's operator keeps them longer (CLI_AUDIT_RETENTION_DAYS, see /docs/self-hosting).

From your terminal:

Terminal
cli audit
cli audit -n 50

Ask your agent:

"Who changed the api's variables yesterday?"

Agents use cli_audit_log. For changes with their reason, cost and an undo button, use the flight recorder (see /docs/flight-recorder).

With the API:

API
GET /v1/projects/:id/audit?limit=50

The answer includes next; pass it as before to page back through older entries.

On-chain receipts

Receipts let anyone check that your audit log hasn't been changed after the fact. When they're on, CLI seals the audit log into a Merkle tree every few hours and writes the root on chain. Turning them on takes an admin.

From your terminal:

Terminal
cli receipts on
cli receipts      # status and recent receipts
cli receipts off

With the API:

API
PUT /v1/projects/:id/receipts
{"enabled": true}

GET /v1/projects/:id/receipts shows whether they're on, which address anchors them, on which chain, and the receipts so far. Turning them off keeps existing receipts checkable.

Verify an entry

  1. Get the proof for an audit entry:
    API
    GET /v1/projects/:id/receipts/proof/:entryId
  2. Send the entry, proof and root to the verifier. It needs no sign-in, so anyone you share them with can check:
    API
    POST /v1/receipts/verify
    {"entry": {…}, "proof": ["0x…"], "root": "0x…", "txHash": "0x…", "chainId": 8453}

The data written on chain is 0x434c4901 ‖ sha256(project id) ‖ root.

Abuse controls and appeals

New accounts get stricter checks: crypto miners are stopped, phishing pages are taken down when they go live, and daily outbound traffic is capped. A service running flat out (above 90% CPU) for a sustained period puts its project on hold.

If your project is affected:

  • On hold for review (ACCOUNT_REVIEW): services are stopped and deploys refused while CLI looks at the activity. You get a project_on_hold event.
  • Suspended by the operators (SUSPENDED_BY_OPERATOR): nothing can be deployed until the suspension is lifted.

To find out why and appeal:

With the API:

API
GET /v1/projects/:id/abuse
POST /v1/abuse/:id/appeal
{"message": "This is a video encoder, not a miner. Here's the repo: …"}

Appeals take an admin. The platform's operators review them in their queue.