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.
| Language | Package | Install |
|---|---|---|
| TypeScript / JS | runberth-sdk | npm install runberth-sdk |
| Python | runberth | pip install runberth |
Both are zero-dependency. Source: github.com/runberth-sh/runberth-sdk.
- 1
provision({ externalId })Creates the customer's agent once - 2
chat(id, message)Wakes it if it is asleep and sends the message - 3
replyComes back to your code
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).
| Method | Does |
|---|---|
| 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:
| Method | Does |
|---|---|
| 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
| Param | Type | Notes |
|---|---|---|
| name | string | Unique per account. Required. |
| template | string | openclaw · zeroclaw · hermes · claude_code · dsh · … (see frameworks) |
| externalId | string | Your own id for this agent. Filterable; idempotency key for provision. |
| instructions | string | Plain-English persona / system prompt. |
| env | {key,value,secret}[] | Seed env vars. Secrets encrypted at rest. |
| idleTtlSeconds | number | Idle 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.
| Method | Does |
|---|---|
| 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 / watch | Work 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 / killEphemeral | Sandboxes with a fixed lifetime that end, disk included, when it runs out. |
| snapshots.list / get / delete | Saved 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 / deliveries | Endpoints 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.
| Method | Does |
|---|---|
| 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.
| Method | Does |
|---|---|
| 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.
| Method | Does |
|---|---|
| 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.
| Method | Does |
|---|---|
| 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 3000A 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.
| Method | Does |
|---|---|
| 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.
| Method | Does |
|---|---|
| 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
| Method | Does |
|---|---|
| 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.
| Method | Does |
|---|---|
| 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.
| Class | When |
|---|---|
| RunBerthAuthError | 401 / 403: bad or under-scoped key |
| RunBerthPaymentRequiredError | 402: plan limit reached, or an add-on needs a paid plan |
| RunBerthNotFoundError | 404: no such agent (or not yours) |
| RunBerthConflictError | 409: name already taken |
| RunBerthRateLimitError | 429: rate limited |
| RunBerthSandboxError | a sandbox call failed; carries code, hint and retryAfterSeconds |
| RunBerthAPIError | any other non-2xx |
| RunBerthConnectionError | never 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.