How to do it in a sandbox
One task each in an AI agent's sandbox, step by step, with working TypeScript and Python.
62 pages
- How to add a custom domain to a sandboxRun runtime domains add app.example.com <sandbox> 3000, set the TXT and CNAME records it prints, then run runtime domains verify.
- How to add Runtime to Claude.ai as a custom connectorIn Claude, open Customize > Connectors, choose Add custom connector, enter https://api.withruntime.com/mcp, and approve in your browser.
- How to add Runtime to Cursor with MCPAdd a runtime server that runs npx -y withruntime mcp to ~/.cursor/mcp.json.
- How to attach a persistent volume to a sandboxCreate a volume with runtime.volumes.create({ sizeMiB }).
- How to back up and restore a sandbox volumeVolumes are backed up daily or on your own schedule. volumes.backup(id) makes a backup now. volumes.restore(backupId) restores it.
- How to block a domain from a sandboxCall sbx.network.set({ internet: true, deny: ["example.com"] }).
- How to build a custom sandbox image from a list of packagesCall runtime.images.build({ name, recipe: { pip, apt, npm } }) once.
- How to build a sandbox image from a DockerfileRun runtime images build . -t web:v1, or pass dockerfile and contextDir to images.build.
- How to call the Runtime REST API with curlSend Authorization: Bearer $RUNTIME_API_KEY to https://api.withruntime.com/v1/....
- How to cap what a single sandbox can costPass maxTotalCostMicros to set a ceiling over the sandbox's whole life.
- How to choose a sandbox's CPU, memory and disk sizePass vcpu, memoryMiB and diskMiB when you create the sandbox.
- How to compare your sandbox costs with E2B, Daytona, Modal and othersRun runtime compare --from e2b, or use another provider's name.
- How to connect your network to sandboxes with WireGuardRun runtime networks wireguard create.
- How to control a Linux desktop in a cloud sandboxCall sbx.desktop.start().
- How to create a read-only API key for monitoring and CIChoose Read only when you create a key at withruntime.com/account/keys.
- How to download files from a sandboxCall sbx.files.readText(path) or read(path) to get one file.
- How to expose a port from a sandbox at an HTTPS URLStart the server with spawn.
- How to extend a sandbox's leaseOn Runtime, you rarely need to extend a lease.
- How to find a sandbox by nameCall Sandbox.getOrCreate("dev").
- How to fork a running sandbox into parallel copiesCall sbx.fork({ count }) to make up to 100 running copies.
- How to give sandboxes a static outbound IP addressRun runtime ips reserve.
- How to handle no_capacity and quota_exceeded errorsThe SDK waits for room.
- How to install apt packages in a sandboxRun sudo apt-get update && sudo apt-get install -y <package> in the sandbox. sudo needs no password, because you are root inside it.
- How to install Python packages with uv in a sandboxuv is preinstalled: run uv venv, then uv pip install <package>, or uv sync in a project that has a uv.lock.
- How to invite your team to a Runtime accountOpen Members, choose Invite, enter the email address and a role, then send.
- How to keep a sandbox runningA Runtime sandbox already runs while it works, with no time limit. persistent: true keeps a paid sandbox running even while it is idle.
- How to label and list sandboxesPass labels: { team: "search" } when you create a sandbox.
- How to make charts with a code interpreterRun matplotlib code with sbx.interpreter.run().
- How to mount an S3 bucket in a sandboxStore the bucket's key as a Runtime secret.
- How to open a cloud sandbox in VS Code with Remote-SSHRun runtime sandboxes ssh config --install once, then in VS Code run Remote-SSH: Connect to Host and enter <id>.runtime.
- How to open a public TCP port on a sandboxRun runtime ports open <sandbox> 5432.
- How to open an interactive terminal in a sandboxRun runtime sandboxes shell <id> from your terminal.
- How to pause a sandbox when it is idleA Runtime sandbox pauses itself after 300 seconds of idle time.
- How to pause and resume a sandboxCall pause() to save its files, memory and running processes.
- How to port-forward a database from a sandbox to your machineRun runtime sandboxes port-forward <id> 5432. localhost:5432 on your machine then reaches Postgres inside the sandbox.
- How to read a sandbox's CPU and memory metricsCall sbx.metrics({ range: "1h" }). latest is the newest reading, and points is the series.
- How to read your Runtime audit logOwners and admins can open Audit log in the account.
- How to receive webhooks for sandbox eventsCall runtime.webhooks.create({ url, events }).
- How to reserve CPU for a sandbox (dedicated vCPUs)Create the sandbox with cpu: "reserved" to guarantee every vCPU.
- How to restrict a sandbox to an allow-list of hostsCreate the sandbox with network: { internet: true, allow: ["pypi.org", "*.pythonhosted.org"] }.
- How to retry sandbox API calls safely with idempotency keysSend the same Idempotency-Key with the same body.
- How to rotate a preview tokenCall sbx.previews.rotate(port).
- How to run a background process in a sandboxCall spawn() with the command.
- How to run Docker inside a sandboxRun sudo enable-docker once in the sandbox.
- How to run Runtime sandboxes from GitHub ActionsMake a key with runtime keys create.
- How to set a daily spending limit for an AI agent's API keySet it on the key's row at withruntime.com/account/keys, or make the key with runtime keys create --daily-limit 25.
- How to set up single sign-on (SAML or OIDC) for RuntimeAn owner connects your identity provider on the Single sign-on page.
- How to snapshot a sandbox and start new ones from itCall sbx.snapshot({ name, retentionDays }).
- How to SSH into a cloud sandboxRun runtime sandboxes ssh <id>.
- How to start a sandbox from a private registry imageStore the registry's credential once with runtime images registry set, then build from the private image and start sandboxes from it.
- How to stream command output from a sandboxPass onStdout to exec (on_stdout in Python), or loop over execStream().
- How to switch from E2B to Runtime by changing one importReplace from "e2b" with from "withruntime/e2b" (Python: from withruntime.e2b import Sandbox) and set RUNTIME_API_KEY.
- How to take a screenshot in a cloud sandboxStart the sandbox's desktop and call sbx.desktop.screenshot() for PNG bytes, or run Playwright's page.screenshot() for a full page.
- How to turn off internet access in a sandboxCreate the sandbox with network: { internet: false }, or call sbx.network.off() at any time.
- How to upload a folder to a sandboxCall sbx.files.upload(localDir, "/workspace/project").
- How to use API keys in a sandbox without exposing themStore the key with runtime secrets set NAME --host api.example.com.
- How to use AWS from a sandbox without storing keysIn IAM, trust https://withruntime.com/oidc.
- How to use JetBrains Gateway with a cloud sandboxRun runtime sandboxes ssh config --install, then add a Gateway SSH connection to <id>.runtime, user runtime, using the OpenSSH config.
- How to use Runtime's OpenAPI specDownload https://api.withruntime.com/v1/openapi.json, an OpenAPI 3.1 document of every route, and feed it to a client generator.
- How to verify a Runtime webhook signatureCompare v1 in Runtime-Signature with the hex HMAC-SHA256 of {t}.{raw body}, keyed with your secret.
- How to wake a sandbox on requestDo nothing: a paused sandbox wakes by itself when an exec, file, process or terminal call, or a visit to a shared port, reaches it.
- How to watch files for changes in a sandboxCall sbx.files.watch(dir, onEvent, { recursive: true }).