# RunBerth CLI: instructions for AI agents Copy this file into your agent's context (CLAUDE.md, AGENTS.md, or a system prompt), or let the agent fetch it from https://runberth.com/docs/cli/llms.txt. It teaches an LLM to operate RunBerth (https://runberth.com): every computer an agent needs (sandboxes, Linux and Windows desktops, Android phones). Agents deployed here run in persistent micro-VMs with storage at /data; they sleep when idle and wake in about a second on the next message or trigger. Billing: plans from $20 a month, and the plan fee becomes usage credit; machines are billed per second at hourly rates, with a 7-day free trial (card needed, usage capped at $20). Details: https://runberth.com/pricing The CLI describes itself offline: `runberth guide` prints its usage guide, and `runberth guide --json` emits the full command and flag manifest, introspected live from the installed CLI. Prefer that manifest, and `runberth --help`, over guessing flags. `--dry-run` on any command prints the HTTP request without sending it. ## Setup 1. Install: curl -fsSL https://runberth.com/install.sh | sh (no Node needed; it checks the download's sha512), or npm install -g runberth-cli (the npm package is runberth-cli; the command is runberth; needs Node 18+. If a flag below is unknown, run npm install -g runberth-cli@latest) 2. Authenticate, first path that works wins: - New user, or no plan yet: runberth onboard --json. It prints one JSON object whose step names what the user must do: sign_in (give them sign_in.url and sign_in.code), checkout (give them checkout_url: the 7-day free trial in Stripe Checkout, card required, nothing charged for 7 days) or billing_action (give them billing_url). After each step run runberth onboard --wait --json, until step is done. Do this before you build anything: no machine starts without a plan or the trial. - RUNBERTH_TOKEN in the environment (an mk_ key or a login token); the CLI reads it before anything else. - Any account, browser or not: runberth login --json prints one JSON line on stderr with user_code and verification_uri_complete; show both to the user and wait for their approval in any signed-in browser. - Email/password account, no browser: runberth login --email --password - No account, user present: runberth signup -e -p -n --json (ask the user for the email and password; never invent them) - No account, do not stop: add --claim-later to runberth create. No login needed; the agent runs under a temporary account for 72 hours. The JSON response carries data.claimUrl (the user opens it to keep the agent) and data.token (a temporary key for that agent; export it as RUNBERTH_TOKEN to operate it). One agent only; template agents must bring their own model key (-e ANTHROPIC_API_KEY=...). 3. Verify: runberth whoami --json prints {authenticated, source, method, expires_at} and exits 4 when no credential is set or a login token expired. It does not call the API, so a wrong mk_ key still reports authenticated; runberth doctor checks it. 4. The email verification wall: until the user clicks the link RunBerth emailed them, create, deploy, start, restart, keys create, and computer creation are refused with HTTP 403 and email_not_verified in the error (exit 4). Ask the user to click the link. To get it again they sign in at https://runberth.com/login, which offers to resend it. Then retry the same command. List, status, logs, and templates work before verification. 5. Long-running automation: once verified, mint a key that never expires: runberth keys create --name my-agent --json (data.raw_key is shown once), and export RUNBERTH_TOKEN=mk_... Full setup procedure, step by step: https://runberth.com/agents.md RUNBERTH_API_URL overrides the API base (default https://api.runberth.com). ## The contract - Pass --json on EVERY command. Results go to stdout: reads print {"meta": {...}, "results": ...}; writes print {"action", "resource", "path", "status", "success", "data"}; chat, status and whoami print their object directly. Errors print "Error: ..." on stderr; API errors include the HTTP status and the API's response body. A 409 also prints {"error": "...", "code": 5} on stdout. Branch on the exit code, never scrape human text. - The global --agent flag sets --json --compact --no-input --no-color --yes. --compact keeps only key fields; leave it off when you need the full body. - Exit codes: 0 success, 1 other error, 2 usage (unknown flag, missing argument, missing --yes), 3 not found (HTTP 404), 4 auth (no credential, expired, HTTP 401/403), 5 API error (other HTTP errors such as 402, 409, 422, 5xx), 6 partial failure, 7 rate limited (HTTP 429), 10 config. - The top-level agent commands (chat, logs, status, env, delete and the rest) take the exact agent name or an ID prefix. Inside a directory linked with runberth init/link, the agent argument can be omitted. Commands whose help shows (exec, files, agents ...) need the full ID. - In a linked directory, chat treats every argument as the message. To reach another agent from there, use runberth chat -a "...". ## Core tasks # Discover templates, create an agent, wait for it, talk to it: runberth templates --json runberth create my-agent --template openclaw --json runberth status my-agent --json # wait for "active" runberth chat my-agent "introduce yourself" --json | jq -r '.response' # No account yet and nobody to ask: deploy now, claim later (72 h, 1 agent): runberth create my-bot --repo https://github.com/you/agent --claim-later --json # Deploy your own code (any framework; Dockerfile at the repo root): runberth create my-bot --json runberth deploy my-bot --source github --repo https://github.com/you/agent --branch main --wait --json # Serve a repo on a public no-login URL (sleeps idle, wakes on the next visit): runberth create my-app --repo https://github.com/you/app --public --port 3000 --json # Encrypted env vars (secret by default; --reload pushes into the running agent): runberth env set my-agent OPENAI_API_KEY=sk-... --reload --json runberth env import my-agent ./prod.env --reload --json runberth env list my-agent --json # Inspect and debug: runberth list --json runberth logs my-agent --level error --json runberth info my-agent --json runberth history my-agent --json # build/deploy attempts + buildLog runberth exec --body-json '{"command":"ls /data"}' --json | jq -r '.results.stdout' # Message an agent AS one of your end users (sticky per-user routing through # the project front door; same --user always reaches the same instance): runberth message my-agent --user cust_42 "where is my order?" --json | jq -r '.data.reply' # Your end users (the people your product serves), each with their own agent: # (end-users, alias users; bodies go in --body-json, fields as in the REST API) runberth users upsert user_42 --display-name "Ada" --tags pro --json # safe on every sign-in runberth users create user_42 --body-json '{"templateId":"openclaw"}' --json # their agent, exactly once runberth users set-policy user_42 --body-json '{"policy":{"llm_spend_cap_cents_per_month":500}}' --json runberth users policy user_42 --json # read; clear-policy removes it runberth users token user_42 --body-json '{"scopes":["chat"],"ttlSeconds":900}' --json # eu_ token runberth users list --json · get · agents · suspend · resume · delete runberth usage get --from 2026-09-01 --to 2026-10-01 --json # per agent, each row has externalUserId runberth usage daily --json # per day # Lifecycle (rarely needed; agents sleep and wake on their own): runberth start my-agent --json runberth sleep my-agent --json runberth restart my-agent --json # also picks up new env vars runberth delete my-agent --yes --json # --yes is REQUIRED non-interactively ## Scheduling Timers inside a sleeping agent do not fire. Put scheduled work on platform triggers: runberth triggers list , and runberth triggers create --type cron --cron "0 9 * * *" --prompt "...". A cron trigger wakes the agent and delivers --prompt as a message on each fire. A custom container can instead serve GET /schedules and RunBerth registers the wakes for it. Details: https://runberth.com/docs/triggers runberth exec takes the full agent ID and a required --body-json: {"command": "..." or ["argv", ...], "detached": false, "timeout": 60}. Words after the agent ID are not sent. timeout defaults to 60 seconds attached or 3,600 seconds detached. A detached call returns executionId at once; fetch or cancel it through the REST API: https://runberth.com/docs/api#exec On agents with detached support, disconnecting does not cancel execution. Do not repeat submission after a lost response without accounting for a command that may already be running. Older agents support attached exec with combined output and no execution ID. Detached submission on those agents returns HTTP 501 with unsupported: outdated vm. Please use a new agent. Use a new agent for detached execution. Restarting an older agent does not add this feature. ## Gotchas - create and delete never hang without a terminal: a missing name, or delete without --yes, exits 2. - Env changes apply on the next boot unless you pass --reload (or run runberth env reload ). - If chat fails with agent_unavailable in the error, the agent is not running: runberth start , wait a few seconds, retry. - A 404 or "not running" on file/exec operations usually means the agent is asleep or errored: start it and retry; do not recreate it. - mk_ keys never expire unless created with --expires-in-days; login tokens do. Use mk_ for automation. - LLM access: most templates work with no model key (RunBerth's model proxy, charged at the provider's list price, no markup, from your AI credits). The claude_code template is the exception: it always needs your own ANTHROPIC_API_KEY as a secret env var. ## Something wrong with these docs? If a command, flag or example here does not match what the CLI does, or a call fails and the error does not tell you what to do, tell RunBerth. Any mk_ key works. Put the X-Request-Id of the failing call in requestId when there is one and name yourself in tool. Never include keys, tokens or env values. curl -X POST https://api.runberth.com/api/v1/feedback \ -H "Authorization: Bearer $RUNBERTH_API_KEY" \ -H "Content-Type: application/json" \ -d '{"kind":"cli","subject":"runberth env set","message":"","tool":"claude-code/2.1.0"}' kind is one of docs, sdk, api, cli, computers, dashboard, other. Capped at 5 reports a minute and 20 a day per account. Reference: https://runberth.com/docs/sdk/feedback ## More - Human-readable CLI reference: https://runberth.com/docs/cli - Drive-RunBerth-from-an-AI-agent guide: https://runberth.com/docs/ai-agents - REST API: https://runberth.com/docs/api - Building a product where every customer gets an agent? Use the SDK from your backend instead: https://runberth.com/docs/build