SDK Reference

Complete reference for both RunBerth SDKs. New here? Start with the Build on RunBerth guide. Methods are shown with their TypeScript names; Python uses the same names in snake_case (setEnv is set_env) with keyword arguments.

LanguagePackageInstall
TypeScript / JSrunberth-sdknpm install runberth-sdk
Pythonrunberthpip install runberth

Both are zero-dependency. Source: github.com/runberth-sh/runberth-sdk.

  1. 1provision({ externalId })Creates the customer's agent once
  2. 2chat(id, message)Wakes it if it is asleep and sends the message
  3. 3replyComes back to your code
Your code provisions an agent for a customer, sends it a message, and gets the reply. A sleeping agent wakes on the message.

Client

The API key defaults to RUNBERTH_API_KEY; the base URL to RUNBERTH_API_URL or api.runberth.com.

import { RunBerth } from 'runberth-sdk'

const runberth = new RunBerth({
  apiKey: 'mk_...',                     // or RUNBERTH_API_KEY
  baseUrl: 'https://api.runberth.com',   // or RUNBERTH_API_URL
  timeout: 60_000,                      // per-request ms
  maxRetries: 2,                        // network + 5xx/429
})

A failed request is retried up to maxRetries times (default 2), waiting 0.5 s, then 1 s, doubling up to 8 s, or the server's Retry-After up to 20 s. GET and DELETE, the lifecycle calls (start, stop, sleep, restart, reloadEnv) and chat, which sends an Idempotency-Key, retry on 429, 500, 502, 503, 504, timeouts and network errors. Other writes retry only on 429 and 503, and when the connection was refused or DNS failed, so nothing was sent; a timeout or another 5xx may already have applied the write, so it is thrown.

Agents

Access via runberth.agents (TS) / client.agents (Python).

MethodDoes
create(params)Create an agent and start its deploy. Prefer template: a bare framework yields a broken image.
provision({externalId, …})Idempotent get-or-create by externalId. The recommended per-customer entry point.
get(id)Fetch one agent.
list({externalId?, name?})List agents, optionally filtered.
chat(id, message, {conversationId?})Send a message, wait for the reply. Auto-wakes a sleeping agent.
start / stop / sleep / restart(id)Lifecycle transitions.
setEnv(id, key, value, {secret})Upsert an env var (secrets encrypted at rest).
listEnv(id) / deleteEnv(id, key)Read / remove env vars.
reloadEnv(id)Push env changes into the running container.
resize(id, {memMb?, diskGb?, alwaysOn?})Change RAM or disk (applies on the next restart) or turn always-on on or off (applies at once). null clears a value back to the base allocation.
setVisibility(id, visibility)'private' (share-link holders only) or 'public' (anyone with the agent URL; a visit wakes it). public needs a verified account.
webhookToken(id)The agent's invoke token and URL; POST to the URL wakes the agent with a payload.
rotateWebhookToken(id)Replace the invoke token. The old one stops working at once.
network(id) / updateNetwork(id, update) / testNetwork(id, destination)Read or change internet policy, exit and private access; try one TCP connection to host:port from inside the agent.
exec(id, command, {timeout?})Run a one-shot shell command (a string, or argv tokens as an array) and wait for it. timeout is seconds, default 60. Wakes a sleeping agent.
logs(id, {limit?, level?})Recent log entries.
delete(id)Tear down the agent (container + volume + network).

Files, skills and share links of an agent hang off runberth.agents:

MethodDoes
files.list(id, path?) / download(id, path)Browse the agent's files; download returns bytes.
files.upload(id, {content, filename, destDir?}) / write(id, path, content)Upload bytes or write a text file.
files.mkdir(id, path) / move(id, from, to) / delete(id, path)Create a folder, move or delete a path.
skills.list(id) / search(id, q, {limit?})The agent's skills (eligible, blocked, unsupported), or search ClawHub.
skills.install(id, {slug?, git?, version?, force?, env?})Install from ClawHub (slug) or a git repo (git).
skills.upload(id, {archive, name?, env?})Install a custom skill from a zip or a bare SKILL.md.
skills.setEnv(id, env) / setAllowlist(id, allowlist)Give a skill the env values it waits on; replace the allowlist (null for no limit).
skills.remove(id, name) / export(id, name)Remove a skill, or download it as a .tar.gz.
shareLinks.create(id, {ttlSeconds?, endUserExternalId?})A link that opens a private agent URL. Default one hour; null lasts until revoked.
shareLinks.list(id) / revoke(id, linkId) / revokeForEndUser(id, externalId)List links, revoke one, or revoke every link bound to an end user.

create / provision parameters

ParamTypeNotes
namestringUnique per account. Required.
templatestringopenclaw · zeroclaw · hermes · claude_code · dsh · … (see frameworks)
externalIdstringYour own id for this agent. Filterable; idempotency key for provision.
instructionsstringPlain-English persona / system prompt.
env{key,value,secret}[]Seed env vars. Secrets encrypted at rest.
idleTtlSecondsnumberIdle seconds before auto-sleep.
// Idempotent per-customer provisioning (recommended)
const agent = await runberth.agents.provision({
  externalId: `customer_${userId}`,
  name: `assistant-${userId}`,
  template: 'openclaw',
})

const { response } = await runberth.agents.chat(agent.id, 'Hello')
await runberth.agents.setEnv(agent.id, 'STRIPE_KEY', 'sk_live_...', { secret: true })
const { root } = await runberth.agents.files.list(agent.id)   // browse / upload / download
await runberth.agents.exec(agent.id, ['ls', '-la', root])     // one-shot shell command
await runberth.agents.sleep(agent.id)
await runberth.agents.delete(agent.id)

Exec waits by default. See command execution for detached Python submission, REST retrieval and cancellation, and timeout defaults.

Sandboxes

Linux machines you create, run commands in, pause, snapshot and end from code. They need a key with the sandboxes scope (or manage). Access via runberth.sandboxes, runberth.ephemeral, runberth.snapshots, runberth.secrets, runberth.usage and runberth.sandboxWebhooks (Python: client.sandbox_webhooks and so on). Sandbox calls throw RunBerthSandboxError with a machine-readable code and hint. See Sandboxes and sandbox events.

MethodDoes
sandboxes.create({name?, from?, size?, screen?, network?, endUser?, env?, idleTimeoutSeconds?, onIdle?, timeLimitSeconds?, keepAwake?, …})Create a sandbox and return a Sandbox object. from is a stock template or a saved snapshot.
sandboxes.get(idOrName) / connect(id) / list({…})Fetch one sandbox, attach to an existing one, or page through yours.
sandbox.run(cmd, {background?, …})Run a command and wait, or start it in the background and get a CommandHandle.
sandbox.files.read / write / list / remove / watchWork with the sandbox's files.
sandbox.url(port) / pause() / kill() / save(name) / update(params)Open a port, pause, end, save a snapshot, or change settings.
sandbox.terminal() / runCode(code)An interactive terminal, or run a code snippet.
ephemeral.createEphemeral / listEphemeral / extendEphemeral / killEphemeralSandboxes with a fixed lifetime that end, disk included, when it runs out.
snapshots.list / get / deleteSaved snapshots and the stock templates.
secrets.set({name, value}) / list / delete(name)Account secrets injected into every new sandbox except forEndUser ones.
usage.list({from, to, sandbox?, endUser?})Sandbox usage records, one per running interval.
sandboxWebhooks.create({url, events}) / list / delete / deliveriesEndpoints that receive signed sandbox events. See sandbox events.

End users

Your own users, keyed by the id you already hold. Access via runberth.endUsers (TS) / client.end_users (Python). See the end users guide.

MethodDoes
upsert(externalId, {displayName?, metadata?, tags?})Create the end user, or update the fields given.
get(externalId)One end user with its agents.
list({status?, tag?, externalIdPrefix?, q?, projectId?, agentId?, sort?, lastActiveBefore?, lastActiveAfter?, cursor?, limit?})One page of end users, newest first. Follow nextCursor for more.
activity(externalId, {limit?})Recent messages with replies, wakes, sleeps and agent creates, newest first.
createAgent(externalId, params?) / agents(externalId)Create the end user's agent exactly once; list their agents.
setPolicy / getPolicy / clearPolicy(externalId)Caps and sizing for every agent the end user owns.
mintToken(externalId, {agentId?, scopes?, ttlSeconds?}) / revokeTokens(externalId)Short-lived eu_ token for their own client; revoke every live token.
suspend / resume / delete(externalId)Pause, restore, or remove the end user with their agents.

Projects

The HTTP front door: route each of your users' messages to their own agent. Access via runberth.projects.

MethodDoes
get(projectId)Fetch a project. Every agent has a projectId.
update(projectId, {name?, newChatPolicy?, maxInstances?, warmPoolSize?})Routing for new end users: 'single', 'assign', 'spawn' (one agent per end user) or 'claim'.
message(projectId, {externalUserId, message, wait?, claimCode?, displayName?})Send an end user's message to their agent (bind, wake, deliver). Waits up to wait seconds (default 30) for the reply.
getMessage(projectId, messageId)Poll a queued message for its reply.
users(projectId) / getUser(projectId, externalUserId)Every bound end user, or one with its agent status.
unbindUser(projectId, externalUserId)Unbind an end user. Their agent rejoins the warm pool.

Swarms

Run one command on many sandboxes and collect the results. Access via runberth.swarms (TS) / client.swarms (Python). See Swarms.

MethodDoes
start({command, count? | inputs?, name?, template? | image?, size?, timeoutSeconds?, concurrency?, resultPath?}, {idempotencyKey?})Start a swarm: one command on many sandboxes. Needs the provision scope. A repeated idempotencyKey returns the first run.
list({limit?})Your runs, newest first.
get(swarmId)One run with every sandbox: status, sandboxId (sbx-...), exit code, output tails and result.
cancel(swarmId)Stop a run; its sandboxes are stopped and ended.
results(swarmId)Every sandbox's outcome, in input order.
wait(swarmId, {intervalMs?, timeoutMs?})Poll until the run completes or is cancelled. Python takes interval and timeout in seconds.

Custom domains

Serve agents and sandbox ports on hostnames you own. Access via runberth.domains (TS) / client.domains (Python, with snake_case names such as set_sandbox_label). Add a domain, create the DNS records in its dnsRecords, and it turns live once the certificate is issued, usually within a few minutes. See custom domains in the API reference.

MethodDoes
add({hostname, agentId?})Add a domain. app.yourco.com needs agentId. *.preview.yourco.com takes none. The response lists the DNS records to create.
list({agentId?}) / get(domainId)Your domains with their state and DNS records.
check(domainId)Check the DNS records and the certificate now, instead of at the next minute.
remove(domainId)Remove a domain. It stops serving at once.
setLabel(domainId, label, agentId)Serve an agent at <label>.<base> under a wildcard domain.
setSandboxLabel(domainId, label, sandboxId, port)Serve a sandbox port at <label>.<base>. Call it again with another sandbox to move the name.
listLabels(domainId) / removeLabel(domainId, label)List or remove the labels under a wildcard domain.
const domain = await runberth.domains.add({ hostname: '*.preview.yourco.com' })
// Create domain.dnsRecords with your DNS provider, then wait for state 'live'.

const sbx = await runberth.sandboxes.create()
await sbx.run('npm run dev -- --port 3000', { background: true })
await sbx.url(3000, { token: false })  // a label serves only a public port
await runberth.domains.setSandboxLabel(domain.id, 'pr-12', sbx.id, 3000)
// https://pr-12.preview.yourco.com/ now serves port 3000

A sandbox label forwards each request, WebSockets included, to the port's own URL. A private port answers 401 through its label. A paused sandbox resumes on the first request. After the sandbox ends, the label answers 404 until you point it at another sandbox. Your app receives the port URL's hostname as Host, not the label's.

Keys

Mint scoped API keys programmatically. Minting requires the caller's key to carry the manage scope. Scopes are provision, deploy, secrets, manage, computers and sandboxes. The default is the first four; manage grants every scope, so a default key also reaches Computers and Sandboxes. A key that should reach only Computers asks for ['computers'], and one for only Sandboxes asks for ['sandboxes']. A key created with projectId works only on that project's front door and usage routes and is refused everywhere else.

MethodDoes
create({name, scopes?, expiresInDays?, projectId?})Mint an account key (mk_). The raw key is returned once.
create({sandbox, ttlSeconds?})Mint a per-sandbox key (msk_) that reaches only that sandbox. Default lifetime one day. The secret is returned once.
list() / list({sandbox})List your account keys, or one sandbox's keys (raw values never returned again).
revoke(id)Revoke a key.
const worker = await runberth.keys.create({ name: 'chat-worker', scopes: ['deploy'] })
// worker.rawKey is shown once. Store it now.
const tenant = await runberth.keys.create({ name: 'tenant-a', projectId: agent.projectId })

Webhooks

Receive signed events instead of polling. The webhooks guide lists every event and covers retries and verification.

MethodDoes
create({url, events?})Subscribe a URL. Returns the signing secret once.
list()List subscriptions, with isActive for each.
deliveries(id, {status?, limit?})The delivery log, newest first. status is 'pending', 'delivered', 'failed' or 'dead'.
replay(deliveryId)Send one delivery again now and return the result.
test(id)Deliver a synthetic ping.
delete(id)Remove a subscription.

Verify a delivery with verifyWebhookSignature({secret, body, signature}) (TS, returns a Promise of boolean) or verify_webhook_signature(secret, body, signature) (Python), both exported at the package top level. Pass the raw body and the X-RunBerth-Signature header.

Billing, account and network

MethodDoes
billing.usage({from?, to?, projectId?, externalUserId?})Per-agent hosting and AI cost over a range (at most 92 days), with externalUserId on each row.
billing.usageDaily({from?, to?})The same costs by day.
account.limits()Your plan, machine counts against their caps, and per-agent size ceilings. Any key works.
network.presets.list() / create({name, allow?, deny?}) / delete(presetId)Saved internet allow and deny lists to apply to agents.

Feedback

Tell RunBerth when a doc is wrong, an example does not run, or a call fails in a way you cannot explain. Built for coding agents. See the feedback guide.

MethodDoes
send({message, kind?, subject?, agentId?, requestId?, statusCode?, tool?, context?})Send one report. Returns the stored row (202).
list()The account's last 50 reports, newest first.
await runberth.feedback.send({
  kind: 'sdk',
  subject: 'agents.chat',
  message: 'chat returned 500 on a fresh agent; docs say sleeping agents auto-wake.',
  requestId: err.requestId,
  statusCode: err.status,
  tool: 'claude-code/2.1.0',
})

Errors

Every failure is a subclass of RunBerthError. API errors expose .status and .detail.

ClassWhen
RunBerthAuthError401 / 403: bad or under-scoped key
RunBerthPaymentRequiredError402: plan limit reached, or an add-on needs a paid plan
RunBerthNotFoundError404: no such agent (or not yours)
RunBerthConflictError409: name already taken
RunBerthRateLimitError429: rate limited
RunBerthSandboxErrora sandbox call failed; carries code, hint and retryAfterSeconds
RunBerthAPIErrorany other non-2xx
RunBerthConnectionErrornever reached RunBerth (network / timeout)
from runberth import RunBerthAPIError

try:
    client.agents.get("nope")
except RunBerthAPIError as err:
    print(err.status, err.detail, err.request_id)

More resources

  • Computers: runberth.computers, desktops your own model drives
  • Networks: internet policy, exits and private access
  • Limits: plan caps, size ceilings and error codes
  • Web apps: public agent URLs, visibility and share links

See also

The Build on RunBerth guide (visual walkthrough), the raw REST API, and the CLI.