SDK

Authentication & scopes

The SDK authenticates with a RunBerth API key (mk_…). It lives on your server and never touches a browser.

Get a key

Mint one from the dashboard (Settings → API keys) or with runberth keys create. Set it as RUNBERTH_API_KEY and both SDKs pick it up automatically.

The RunBerth dashboard API keys page with the scope picker open
A default key is full-access; open Advanced to scope it down.

Scopes

Every key carries scopes. Hand a subsystem the narrowest key it needs. A leaked key can then only do what its scope allows. manage covers the ordinary API. Fleet requires explicit permission.

ScopeGrants
provisioncreate agents
deploystart / stop / restart / sleep / chat
secretsread / write env vars
manageordinary API access, including delete and key management; Fleet requires its own permission
fleetFleet API (preview); returns a fleet ID with the key; cannot be restricted to one project
computersthe Computers product (MCP and /api/v1/computers); a key with only this scope reaches nothing else, and manage or full access reach Computers too
sandboxesSandboxes (create, run, snapshots, secrets, sandbox webhooks); manage reaches them too. Starting a swarm needs provision

Mint a scoped key

A background worker that only chats to existing agents needs deploy, not provision, secrets, or manage. Minting keys itself requires a manage key.

Without scopes a key gets provision, deploy, secrets and manage; computers and sandboxes are never added for you (manage already covers them). Pass projectId (project_id in Python) to tie a key to one project: it then works only on that project's front door and usage routes and is refused everywhere else. Use it for a per-tenant or partner-facing service.

const worker = await runberth.keys.create({
  name: 'chat-worker',
  scopes: ['deploy'],   // chat/start/stop only
})
// worker.rawKey is shown once. Hand it to the worker as RUNBERTH_API_KEY.

const tenant = await runberth.keys.create({ name: 'tenant-a', projectId: agent.projectId })

Fleet API (preview)

Create a Fleet key in Settings → API keys. Open Advanced and select Fleet (preview). Clear the other permissions if this key only needs the Fleet API. Leave the project set to the whole account. Copy the key when it appears and copy its Fleet ID. You can copy the fleet ID again from the key list. No separate enablement request is needed.

The key creation response includes raw_key and fleet_id. A Fleet-only key authenticates requests under /v1/fleets/{fleet_id}; it cannot manage account keys or replace a key used by the ordinary CLI. You can combine Fleet with ordinary permissions. Existing nova keys keep working with their bound fleet ID. The account's normal billing and usage limits apply.

export RUNBERTH_FLEET_KEY='your-key'
export RUNBERTH_FLEET_ID='your-fleet-id'
curl "https://api.runberth.com/v1/fleets/$RUNBERTH_FLEET_ID/agents" \
  -H "Authorization: Bearer $RUNBERTH_FLEET_KEY"

Fleet is a preview. Use non-critical workloads while end-to-end verification of recovery, bundle application, rollouts and erasure continues. Endpoint availability is not a claim that every failure and recovery path has completed qualification.

Per-sandbox keys

To let code inside or next to one sandbox drive only that sandbox, mint a per-sandbox key (msk_…) with keys.create({ sandbox }). It lasts one day by default (60 seconds to 30 days) and its secret is returned once.

const key = await runberth.keys.create({ sandbox: sandbox.id, ttlSeconds: 3600 })
// key.secret is shown once.
Dashboard sessions and admin keys have ordinary full access. Fleet still requires its own permission. Scope enforcement applies to user mk_ keys, so restricted keys are genuinely restricted.