# Runtime > Runtime is a cloud of Linux machines: sandboxes for AI agents, functions, apps, sites, containers, CI/CD, scheduled jobs, browsers, desktops, notebooks and dev environments. Each machine is a Firecracker microVM with its own kernel, disk and network, made in milliseconds and billed for the CPU it uses and the memory it holds. Usage is billed as measured, at the price card's rates. The API is at `https://api.withruntime.com/v2` (version 2026-10-27), described by https://api.withruntime.com/v2/openapi.json and the API reference below. Every call takes an API key as `Authorization: Bearer `; the SDKs, the CLI (`npx withruntime`) and the MCP server read it from `RUNTIME_API_KEY`. ## Prices - CPU: $0.03 per busy vCPU-hour - Memory: $0.008 per GB-hour - Function calls: $0.20 per million - CI/CD: $0.001 per vCPU-minute, 4 GiB each - Warm: $0.18 per GB-month - Standard: $0.10 per GB-month - Cold: $0.02 per GB-month - Traffic out: $0.03 per GB - Dedicated IPv4: $5 per address, a month - WireGuard tunnel: $5 a month, 16 devices - Traffic in is free. No traffic out is free. - Pro: $25 a month, $25 of usage included - Growth: $99 a month, $110 of usage included - Scale: $499 a month, $575 of usage included - Enterprise: $24,990 a year, $3,000 of usage included each month Every price and limit: https://withruntime.com/docs/reference/pricing.md ## Products - [Sandboxes](https://withruntime.com/docs/sandboxes.md): A Linux machine for code you do not fully trust, such as an AI agent's: run anything in it, pause it with its memory kept, and resume it where it was. Starts at 2 vCPU, 4 GB of memory and 4 GB of disk; pauses after 300 seconds idle. API: https://withruntime.com/docs/reference/sandboxes.md - [Functions](https://withruntime.com/docs/functions.md): Answer HTTP requests with one TypeScript handler that pauses when idle and resumes on the next request. Starts at 1 vCPU, 1 GB of memory and 4 GB of disk; pauses after 60 seconds idle. API: https://withruntime.com/docs/reference/functions.md - [Apps](https://withruntime.com/docs/apps.md): Keep a web app running on port 8080, started the way Render and Heroku start one. Starts at 2 vCPU, 2 GB of memory and 4 GB of disk; never pauses for being idle. API: https://withruntime.com/docs/reference/apps.md - [Sites](https://withruntime.com/docs/sites.md): Serve a folder of static files at an HTTPS address, paused when nobody visits. Starts at 1 vCPU, 1 GB of memory and 4 GB of disk; pauses after 60 seconds idle. API: https://withruntime.com/docs/reference/sites.md - [CI/CD](https://withruntime.com/docs/ci.md): Run a repository's checks on a machine with git, Docker, Node, Bun and Python, or as a GitHub Actions runner. Starts at 4 vCPU, 16 GB of memory and 16 GB of disk; pauses after 300 seconds idle. API: https://withruntime.com/docs/reference/ci.md - [Browsers](https://withruntime.com/docs/browsers.md): A headless Chromium for an agent, driven with Playwright or Puppeteer over the Chrome DevTools Protocol. Starts at 2 vCPU, 4 GB of memory and 4 GB of disk; pauses after 60 seconds idle. API: https://withruntime.com/docs/reference/browsers.md - [Desktops](https://withruntime.com/docs/desktops.md): A Linux desktop with Chromium for an agent that uses a computer, its screen read and driven through the API, and shown in the browser and to VNC clients. Starts at 2 vCPU, 4 GB of memory and 4 GB of disk; pauses after 300 seconds idle. API: https://withruntime.com/docs/reference/desktops.md - [Notebooks](https://withruntime.com/docs/notebooks.md): JupyterLab with NumPy, pandas and matplotlib, its kernels kept in memory while it is paused. Starts at 2 vCPU, 4 GB of memory and 4 GB of disk; pauses after 300 seconds idle. API: https://withruntime.com/docs/reference/notebooks.md - [Dev environments](https://withruntime.com/docs/workspaces.md): A development environment with VS Code in the browser, like Codespaces and Gitpod. Starts at 4 vCPU, 8 GB of memory and 16 GB of disk; pauses after 30 minutes idle. API: https://withruntime.com/docs/reference/workspaces.md - [Containers](https://withruntime.com/docs/containers.md): Run one OCI image from any registry, reached at an HTTPS address. Starts at 1 vCPU, 1 GB of memory and 4 GB of disk; pauses after 300 seconds idle. API: https://withruntime.com/docs/reference/containers.md - [Jobs](https://withruntime.com/docs/jobs.md): Run a command on a schedule, or once, each run on a fresh machine billed only while it runs. API: https://withruntime.com/docs/reference/jobs.md - [Images](https://withruntime.com/docs/images.md): Build your own image from a recipe, a Dockerfile or any public OCI image, and boot every product from it. API: https://withruntime.com/docs/reference/images.md ## Guides - [Run an agent's code](https://withruntime.com/docs/agent-loop.md): Run code an AI model writes in a sandbox, read its result and feed failures back to the model. - [Changelog](https://withruntime.com/changelog.md): What shipped in Runtime, newest first. - [Commands and processes](https://withruntime.com/docs/commands.md): Run a command to its end, or start a process and talk to it while it runs. - [Errors and retries](https://withruntime.com/docs/errors.md): The shape of every error, which ones the SDKs retry, and how to make a retried call safe. - [Files](https://withruntime.com/docs/files.md): Read, write, list and move files in a sandbox, of any size. - [Identity tokens](https://withruntime.com/docs/identity-tokens.md): Let code in a sandbox reach AWS, Google Cloud or your own API with a short-lived signed token, and no stored key. - [API keys and access](https://withruntime.com/docs/keys.md): Authenticate with an API key, and give each key only the actions it needs. - [Sandbox lifecycle](https://withruntime.com/docs/lifecycle.md): Every state a sandbox can be in, and which call or event moves it between them. - [Limits](https://withruntime.com/docs/limits.md): How large a sandbox can be, how many can run at once, and how to read your account's limits. - [MCP](https://withruntime.com/docs/mcp.md): Give a coding agent Runtime's tools and Runtime's docs over MCP. - [Networking](https://withruntime.com/docs/networking.md): Control where a sandbox can connect out, and reach a sandbox from outside over HTTPS or TCP. - [Pause and resume](https://withruntime.com/docs/pause-and-resume.md): Pause a sandbox to stop paying for its CPU and memory, and resume it where it left off. - [Pricing](https://withruntime.com/docs/pricing.md): What Runtime charges for, how each charge is measured, and what each plan includes. - [Products](https://withruntime.com/docs/products.md): Every Runtime product, what each one is for and the size it starts at. - [SDKs and the CLI](https://withruntime.com/docs/sdks.md): Install an SDK or the CLI, and find any call's example in every language. - [Secrets](https://withruntime.com/docs/secrets.md): Let code in a sandbox call an API with your key without the key ever entering the sandbox. - [Snapshots, forks and images](https://withruntime.com/docs/snapshots.md): Keep a sandbox's disk and memory as a snapshot, start new sandboxes from it, and fork a running sandbox. - [Quickstart](https://withruntime.com/docs/start.md): Create a sandbox, run a program in it and delete it, in about a minute. - [Switch from Daytona](https://withruntime.com/docs/switch-from-daytona.md): Move code from Daytona's SDK to Runtime: each Daytona call and the Runtime call that replaces it. - [Switch from E2B](https://withruntime.com/docs/switch-from-e2b.md): Move code from E2B's SDK to Runtime: each E2B call and the Runtime call that replaces it. - [Switch from AWS Lambda](https://withruntime.com/docs/switch-from-lambda.md): Run code you used to run in AWS Lambda or a Lambda microVM in a Runtime sandbox instead. - [Switch from Modal](https://withruntime.com/docs/switch-from-modal.md): Move code from Modal Sandboxes to Runtime: each Modal call and the Runtime call that replaces it. - [Switch from Vercel Sandbox](https://withruntime.com/docs/switch-from-vercel.md): Move code from Vercel Sandbox to Runtime: each Vercel call and the Runtime call that replaces it. - [Serve a web app](https://withruntime.com/docs/web-app.md): Start a web server in a sandbox and share its port at a private HTTPS address. ## API reference - [apps](https://withruntime.com/docs/reference/apps.md) - [browsers](https://withruntime.com/docs/reference/browsers.md) - [builds](https://withruntime.com/docs/reference/builds.md) - [ci](https://withruntime.com/docs/reference/ci.md) - [containers](https://withruntime.com/docs/reference/containers.md) - [desktops](https://withruntime.com/docs/reference/desktops.md) - [domains](https://withruntime.com/docs/reference/domains.md) - [egress-ips](https://withruntime.com/docs/reference/egress-ips.md) - [feedback](https://withruntime.com/docs/reference/feedback.md) - [functions](https://withruntime.com/docs/reference/functions.md) - [identities](https://withruntime.com/docs/reference/identities.md) - [images](https://withruntime.com/docs/reference/images.md) - [job-runs](https://withruntime.com/docs/reference/job-runs.md) - [jobs](https://withruntime.com/docs/reference/jobs.md) - [keys](https://withruntime.com/docs/reference/keys.md) - [me](https://withruntime.com/docs/reference/me.md) - [networks](https://withruntime.com/docs/reference/networks.md) - [notebooks](https://withruntime.com/docs/reference/notebooks.md) - [otel](https://withruntime.com/docs/reference/otel.md) - [overview](https://withruntime.com/docs/reference/overview.md) - [ports](https://withruntime.com/docs/reference/ports.md) - [previews](https://withruntime.com/docs/reference/previews.md) - [pricing](https://withruntime.com/docs/reference/pricing.md) - [projects](https://withruntime.com/docs/reference/projects.md) - [roles](https://withruntime.com/docs/reference/roles.md) - [sandboxes](https://withruntime.com/docs/reference/sandboxes.md) - [secrets](https://withruntime.com/docs/reference/secrets.md) - [sites](https://withruntime.com/docs/reference/sites.md) - [snapshots](https://withruntime.com/docs/reference/snapshots.md) - [tunnels](https://withruntime.com/docs/reference/tunnels.md) - [usage](https://withruntime.com/docs/reference/usage.md) - [v1-key-scopes](https://withruntime.com/docs/reference/v1-key-scopes.md) - [volumes](https://withruntime.com/docs/reference/volumes.md) - [webhooks](https://withruntime.com/docs/reference/webhooks.md) - [workspaces](https://withruntime.com/docs/reference/workspaces.md) Every guide whole: https://withruntime.com/llms-full.txt --- # Run an agent's code An agent that writes code needs a place to run it that can't reach your machine. Give each agent session one sandbox: the model's code runs there, and files and installed packages stay between steps. ## The loop Each step writes the model's code to a file, runs it with [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) and returns the result to the model. A command that fails returns a result with a non-zero `exitCode` and its `stderr`, so the model can read the error and try again. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); // Stand-ins for what your model writes: a first attempt with a bug, then the fix. const attempts = ["rows = [i * i for i in range(5)]\nprint(total)\n", "rows = [i * i for i in range(5)]\nprint(sum(rows))\n"]; const sandbox = await runtime.sandboxes.create({ labels: { session: "example" } }); try { for (const [step, code] of attempts.entries()) { const path = `/tmp/step${step}.py`; await runtime.sandboxes.write(sandbox.id, new TextEncoder().encode(code), { path }); const result = await runtime.sandboxes.exec(sandbox.id, { cmd: ["python3", path], timeoutSeconds: 30 }); // Return this to the model as the tool's result. const feedback = { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, state: result.state }; console.log(step, JSON.stringify(feedback)); if (result.exitCode === 0) break; } } finally { await runtime.sandboxes.delete(sandbox.id); } ``` ```python from withruntime.generated import Runtime runtime = Runtime() attempts = ["print(total)\n", "print(sum(i * i for i in range(5)))\n"] sandbox = runtime.sandboxes.create(labels={"session": "example"}) try: for step, code in enumerate(attempts): path = f"/tmp/step{step}.py" runtime.sandboxes.write(sandbox.id, code.encode(), path=path) result = runtime.sandboxes.exec(sandbox.id, cmd=["python3", path], timeout_seconds=30) print(step, result.exit_code, result.stdout or result.stderr.splitlines()[-1]) if result.exit_code == 0: break finally: runtime.sandboxes.delete(sandbox.id) ``` ## What to return to the model Return [`exitCode`](./reference/sandboxes#process), [`stdout`](./reference/sandboxes#process) and [`stderr`](./reference/sandboxes#process). Two more fields say when the output is not the whole story: - [`state`](./reference/sandboxes#process): `timed_out` when it was still running at its timeout and was stopped. Set the limit with [`timeoutSeconds`](./reference/sandboxes#execrequest): Seconds it may run before it is stopped (`1.5` for 1,500 ms); it runs to its end when omitted or 0. - [`stdoutTruncated`](./reference/sandboxes#process) and [`stderrTruncated`](./reference/sandboxes#process): stdout holds only part of what it wrote (its first 1 MiB). Have the model write large output to a file and read the part it needs. ## Long-running and interactive code [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) runs a command to its end. For a server, a watcher or an interpreter the model keeps talking to, start it with [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) and [`wait`](./reference/sandboxes#execrequest) false, send it input with [`POST /v2/sandboxes/{id}/processes/{process}:write`](./reference/sandboxes#writeprocess) and read its output with [`GET /v2/sandboxes/{id}/processes/{process}/output`](./reference/sandboxes#processoutput). See [commands and processes](./commands). ## One sandbox per session - Create the sandbox when the session starts, and delete it when the session ends. Label it ([`labels`](./reference/sandboxes#sandboxcreate)) with the session's ID, so you can find and delete sandboxes a crashed worker left behind with [`GET /v2/sandboxes`](./reference/sandboxes#list-sandboxes). - Give it a name ([`name`](./reference/sandboxes#sandboxcreate)) and set [`getOrCreate`](./reference/sandboxes#sandboxcreate) to reuse the session's sandbox after a restart: With a name: the sandbox of that name when there is one, else a new one. - Between steps, a sandbox with nothing happening pauses by itself and resumes on the next call. See [pause and resume](./pause-and-resume). - To start many sessions from the same prepared state, prepare one sandbox and fork it with [`POST /v2/sandboxes/{id}:fork`](./reference/sandboxes#fork). See [snapshots and forks](./snapshots). ## Limit what the code can reach The model's code runs as root inside its own kernel, never on your servers. To control what it can reach on the network, set the sandbox's network rules with [`PUT /v2/sandboxes/{id}/network`](./reference/sandboxes#setnetwork) ([networking](./networking)). To let it call an API without seeing the key, store the key as a [secret](./secrets). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/agent-loop.md. Add a code-execution tool to this project's agent that runs each piece of model-written code in one Runtime sandbox per session, returns stdout, stderr and the exit code to the model, and deletes the sandbox when the session ends. > > This page as Markdown: https://withruntime.com/docs/agent-loop.md --- # Apps Keep a web app running on port 8080, started the way Render and Heroku start one. A machine that keeps a web app in /app running on port 8080 (its Procfile's `web:`, else `npm start`, else `python3 app.py`, as Render and Heroku start one), reached at its preview. It never pauses for being idle. | Default | Value | | --- | --- | | vCPUs | 2 | | Memory | 2 GB | | Disk | 4 GB | | Image | `runtime/standard` | | Pauses when idle | Never | [`POST /v2/apps`](./reference/apps#create-a-app) takes the same [SandboxCreate](./reference/sandboxes#sandboxcreate) as a [sandbox](./sandboxes); every field overrides a default above. An app never pauses, so it is billed for its memory, $0.008 per GB-hour, the whole time it runs. ## Deploy an app Upload the app to `/app`, then restart its server. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const app = await runtime.apps.create(); try { await app.files.write("/app/app.py", `from http.server import BaseHTTPRequestHandler, HTTPServer class Hello(BaseHTTPRequestHandler): def do_GET(self): self.send_response(200) self.end_headers() self.wfile.write(b"hello from a Runtime app") HTTPServer(("", 8080), Hello).serve_forever() `); await app.exec("sudo pkill -f runtime-app || true; sudo -E -u runtime runtime-app", { wait: false }); const preview = (await runtime.previews.create(app.id, { port: 8080 })).info; const open = () => fetch(preview.url, { headers: { "x-runtime-preview-token": preview.token! } }); let page = await open(); for (let i = 0; i < 40 && page.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); page = await open(); } console.log(page.status, await page.text()); if (page.status !== 200) throw new Error(`the app answered ${page.status}`); } finally { await app.delete(); } ``` ## Next steps - Every call on an app: [App](./reference/apps). - Keep data across restarts on a volume: [`volumes`](./reference/sandboxes#sandboxcreate). - A handler that pauses between requests costs less: [functions](./functions). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/apps.md. Deploy this project as a Runtime app: upload it to /app, make sure its Procfile's `web:` (or `npm start`) listens on port 8080, share the port with a preview and print its url. > > This page as Markdown: https://withruntime.com/docs/apps.md --- # Browsers A headless Chromium for an agent, driven with Playwright or Puppeteer over the Chrome DevTools Protocol. A machine running headless Chromium, driven over the Chrome DevTools Protocol at its preview on port 9222: one WebSocket address for Playwright's `connectOverCDP` and Puppeteer's `connect`, as Browserbase gives one. It pauses after 60 seconds with nothing happening, its memory kept, and a connection resumes it. | Default | Value | | --- | --- | | vCPUs | 2 | | Memory | 4 GB | | Disk | 4 GB | | Image | `runtime/browsers` | | Pauses when idle | After 60 seconds | [`POST /v2/browsers`](./reference/browsers#create-a-browser) takes the same [SandboxCreate](./reference/sandboxes#sandboxcreate) as a [sandbox](./sandboxes); every field overrides a default above. ## Connect to the browser Share port 9222 with a preview. Chromium's DevTools address answers there. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const browser = await runtime.browsers.create(); try { const preview = (await runtime.previews.create(browser.id, { port: 9222 })).info; const open = () => fetch(`${preview.url}json/version`, { headers: { "x-runtime-preview-token": preview.token! } }); let answer = await open(); for (let i = 0; i < 40 && answer.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); answer = await open(); } const version = await answer.json(); console.log(version.Browser); // Chrome/... if (!String(version.Browser).startsWith("Chrome/")) throw new Error(JSON.stringify(version)); } finally { await browser.delete(); } ``` To drive it, pass the preview's address to Playwright's `chromium.connectOverCDP(url, { headers })` or Puppeteer's `puppeteer.connect`, with the token in the `x-runtime-preview-token` header. ## Next steps - Every call on a browser: [Browser](./reference/browsers). - A whole desktop for an agent that uses a computer: [desktops](./desktops). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/browsers.md. Give this project's agent a Runtime browser: create one, share port 9222 with a preview, and connect Playwright with `chromium.connectOverCDP` to the preview's url with its token in the `x-runtime-preview-token` header. Delete the browser when the agent is done. > > This page as Markdown: https://withruntime.com/docs/browsers.md --- # Changelog What shipped in Runtime Cloud, newest first. Runtime ships every day. Each entry is something you can use or see; the guides hold the current terms, and [pricing](./pricing) holds the current rates. Each day, and each entry, also has a page of its own at [withruntime.com/changelog](https://withruntime.com/changelog), and every entry arrives in the [RSS feed](https://withruntime.com/changelog/feed.xml). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/changelog/feed.xml and tell me which changes since this project last updated its Runtime SDK affect its code, and what to change. > > This page as Markdown: https://withruntime.com/docs/changelog.md --- # CI/CD Run a repository's checks on a machine with git, Docker, Node, Bun and Python, or as a GitHub Actions runner. A machine that runs a repository's checks to their end (its `run`) with git, Docker, Node, Bun, Python and a compiler, and is stopped then. As an Actions runner, it starts GitHub's runner for the one job of its just-in-time configuration (`start` `runtime-runner`, `RUNNER_JITCONFIG` in its environment) and ends with it. | Default | Value | | --- | --- | | vCPUs | 4 | | Memory | 16 GB | | Disk | 16 GB | | Image | `runtime/ci` | [`POST /v2/ci`](./reference/ci#create-a-ci) takes the same [SandboxCreate](./reference/sandboxes#sandboxcreate) as a [sandbox](./sandboxes); every field overrides a default above. You pay for the CPU the checks use, $0.03 per busy vCPU-hour, and nothing once they end. ## Run a repository's checks Give the checks as [`run`](./reference/sandboxes#sandboxcreate), or run them with [`POST /v2/ci/{id}:exec`](./reference/ci#exec) as here. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const ci = await runtime.ci.create(); try { const checks = await ci.exec( "git clone --depth 1 https://github.com/sindresorhus/is /workspace/is && cd /workspace/is && npm install --silent && npx tsc --noEmit && echo checks passed", { timeoutSeconds: 300 }, ); console.log(checks.exitCode, checks.stdout.trim().split("\n").at(-1)); // 0 checks passed if (checks.exitCode !== 0) throw new Error(checks.stderr); } finally { await ci.delete(); } ``` ## Run GitHub Actions jobs To run one Actions job, create a CI machine with `start` set to `runtime-runner` and the job's just-in-time configuration in `RUNNER_JITCONFIG` ([`env`](./reference/sandboxes#sandboxcreate)). It runs that job and ends with it. ## Next steps - Every call on a CI machine: [Ci](./reference/ci). - Run checks on a schedule: [jobs](./jobs). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/ci.md. Run this repository's tests on a Runtime CI machine: create it with `run` set to clone the repository and run the tests, wait for it to stop, and print its exit code and the last lines of its output. > > This page as Markdown: https://withruntime.com/docs/ci.md --- # Commands and processes ## Run a command to its end [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) takes an [ExecRequest](./reference/sandboxes#execrequest) and returns the [Process](./reference/sandboxes#process) it ran as, with its [`stdout`](./reference/sandboxes#process) and [`stderr`](./reference/sandboxes#process). Runs a command as a process and returns it once it ended, with its output; with wait false, at once, while it runs. A paused sandbox is resumed first. Asked again with the same Idempotency-Key, it runs nothing more: it returns the first run's process, waiting for its end while it runs. | Field | | | --- | --- | | [`cmd`](./reference/sandboxes#execrequest) | The command: text, run by `bash -lc` (`"npm test"`), or a list, the program and its arguments run without a shell (`["npm", "test"]`). | | [`cwd`](./reference/sandboxes#execrequest) | The directory it runs in; the user's home when omitted. | | [`env`](./reference/sandboxes#execrequest) | Environment variables to add. | | [`stdin`](./reference/sandboxes#execrequest) | Bytes sent to its standard input. | | [`timeoutSeconds`](./reference/sandboxes#execrequest) | Seconds it may run before it is stopped (`1.5` for 1,500 ms); it runs to its end when omitted or 0. | For pipes, `&&` or shell variables, run the command through a shell: `["bash", "-c", "cd /tmp && ls | wc -l"]`. Keep untrusted input out of the shell's text: pass it in `env` or `stdin`. ```python import base64 from withruntime.generated import Runtime runtime = Runtime() sandbox = runtime.sandboxes.create() try: words = base64.b64encode(b"one two three\n").decode() result = runtime.sandboxes.exec(sandbox.id, cmd=["wc", "-w"], stdin=words) print(result.stdout.strip()) # 3 assert result.stdout.strip() == "3", result finally: runtime.sandboxes.delete(sandbox.id) ``` ## Start a process [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) with [`wait`](./reference/sandboxes#execrequest) false starts a program and returns its [Process](./reference/sandboxes#process) at once, while it runs. Use it for servers, watchers and interpreters. - [`GET /v2/sandboxes/{id}/processes/{process}/output`](./reference/sandboxes#processoutput) reads its output from a byte cursor. [`waitSeconds`](./reference/sandboxes#processoutput): Seconds to wait for output past the cursor or its exit, at most 8. - [`POST /v2/sandboxes/{id}/processes/{process}:write`](./reference/sandboxes#writeprocess) sends it input, when it was started with [`stdinOpen`](./reference/sandboxes#execrequest). - [`POST /v2/sandboxes/{id}/processes/{process}:signal`](./reference/sandboxes#signalprocess) sends it a signal, such as `SIGTERM`. - Each output read returns the process too: its [`state`](./reference/sandboxes#process), and its [`exitCode`](./reference/sandboxes#process) once it ended. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const sandbox = await runtime.sandboxes.create({}); try { const p = await runtime.sandboxes.exec(sandbox.id, { cmd: "for i in 1 2 3; do echo line $i; done", wait: false }); let cursor = 0; let text = ""; for (let reads = 0; reads < 10; reads++) { const out = await runtime.sandboxes.processOutput(sandbox.id, p.id, { cursor, waitSeconds: 2 }); for (const chunk of out.chunks) text += chunk.text; cursor = out.nextCursor; if (out.process && out.process.state !== "running") break; } console.log(text); if (!text.includes("line 3")) throw new Error(text); } finally { await runtime.sandboxes.delete(sandbox.id); } ``` ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/commands.md. In this project, run short commands with exec and servers or interactive programs as processes, and make sure every process is stopped or its sandbox deleted when the work ends. > > This page as Markdown: https://withruntime.com/docs/commands.md --- # Containers Run one OCI image from any registry, reached at an HTTPS address. A machine that runs one OCI image from any registry under Docker on its own network (`start` `runtime-container `), the port it listens on reached at its preview, as Cloud Run and Fly Machines run one. | Default | Value | | --- | --- | | vCPUs | 1 | | Memory | 1 GB | | Disk | 4 GB | | Image | `runtime/standard` | | Pauses when idle | After 300 seconds | Name the image in the `RUNTIME_CONTAINER_IMAGE` environment variable ([`env`](./reference/sandboxes#sandboxcreate)). With none, it runs `nginx:stable`. Every other field of [SandboxCreate](./reference/sandboxes#sandboxcreate) overrides a default above. ## Run an image ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const container = await runtime.containers.create({ env: { RUNTIME_CONTAINER_IMAGE: "traefik/whoami" } }); try { const preview = (await runtime.previews.create(container.id, { port: 80 })).info; const open = () => fetch(preview.url, { headers: { "x-runtime-preview-token": preview.token! } }); let page = await open(); for (let i = 0; i < 120 && page.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); // the image is still being pulled page = await open(); } console.log(page.status, (await page.text()).split("\n")[0]); // 200 Hostname: ... if (page.status !== 200) throw new Error(`the container answered ${page.status}`); } finally { await container.delete(); } ``` ## Next steps - Every call on a container: [Container](./reference/containers). - Boot your own image as the whole machine instead: [images](./images). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/containers.md. Run this project's container image on Runtime: create a container with RUNTIME_CONTAINER_IMAGE set to the image, share the port it listens on with a preview and print its url. > > This page as Markdown: https://withruntime.com/docs/containers.md --- # Desktops A Linux desktop with Chromium for an agent that uses a computer: the agent reads its screen with [`GET /v2/desktops/{id}/screenshot`](./reference/desktops#screenshot) and moves, clicks, scrolls and types with [`POST /v2/desktops/{id}:act`](./reference/desktops#act), and you watch it in the browser or a VNC client. A machine running a Linux desktop with Chromium, for agents that use a computer: screenshot returns what its screen shows and act moves and clicks its mouse and types on its keyboard. It is shown in the browser through noVNC at its preview on port 6080 and to VNC clients on 5900. It pauses after 300 seconds with nothing happening, its memory kept. | Default | Value | | --- | --- | | vCPUs | 2 | | Memory | 4 GB | | Disk | 4 GB | | Image | `runtime/desktops` | | Pauses when idle | After 300 seconds | [`POST /v2/desktops`](./reference/desktops#create-a-desktop) takes the same [SandboxCreate](./reference/sandboxes#sandboxcreate) as a [sandbox](./sandboxes); every field overrides a default above. ## Use the computer A screenshot is the screen's PNG (or a JPEG, with `format: "jpeg"`), at its own size, 1280 by 800. An act runs its steps in order, as one call: each a `move`, `click`, `mouseDown`, `mouseUp`, `drag`, `scroll`, `type`, `key` or `wait`; it returns where the mouse is then. Coordinates are pixels from the screen's top left corner, as in the screenshot, so a model's click lands where it saw. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const desktop = await runtime.desktops.create(); try { const before = await desktop.screenshot(); // Chromium is open on the desktop: focus its address bar, type a URL and go. const acted = await desktop.act([ { type: "key", keys: "ctrl+l" }, { type: "type", text: "https://example.com" }, { type: "key", keys: "Return" }, { type: "wait", ms: 1500 }, { type: "click", x: 640, y: 400 }, ]); const after = await desktop.screenshot({ format: "jpeg", quality: 70 }); console.log(before.length > 0, after.length > 0, acted.cursor); // true true { x: 640, y: 400 } } finally { await desktop.delete(); } ``` | Step | Takes | | --- | --- | | `move` | `x`, `y` | | `click` | `x`, `y` (where the mouse is when omitted), `button` (`left`, `middle`, `right`), `count` (2 a double click, 3 a triple click), `keys` held (`shift`, `ctrl+alt`) | | `mouseDown`, `mouseUp` | `button` | | `drag` | `x`, `y` to press at, `toX`, `toY` to release at, `button` | | `scroll` | `dy` wheel clicks down (negative up), `dx` right (negative left), `x`, `y`, `keys` held | | `type` | `text`, any Unicode, at most 8,192 characters an act | | `key` | `keys`: chords in turn, space-separated, in X key names (`ctrl+l`, `Return`, `ctrl+shift+t`, `Escape`) | | `wait` | `ms`, at most 20,000 an act | An act types and waits at most 45 seconds in all, a typed character taking 7 ms: send longer text as several acts. It stops at the first step that fails, or at a key name X does not know, returned 409 `act_failed` with the step's number in `details.step`; the steps before it ran, and every key and button it held down is let go. Both are verbs of every machine, so a sandbox whose image runs an X display at `:1` with `scrot` and `xdotool` takes them too; one with no display returns 409 `display_not_running`. A program starts on the desktop as a process with `DISPLAY=:1` in its environment, for example `chromium https://example.com` through [`POST /v2/desktops/{id}:exec`](./reference/desktops#exec) with `wait: false`. ## Watch the desktop ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const desktop = await runtime.desktops.create(); try { const preview = (await runtime.previews.create(desktop.id, { port: 6080 })).info; const view = `${preview.url}vnc.html?runtime_preview_token=${preview.token}`; let page = await fetch(view); for (let i = 0; i < 40 && page.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); page = await fetch(view); } console.log(page.status, view.split("?")[0]); // open the full address in a browser to watch if (page.status !== 200) throw new Error(`the desktop answered ${page.status}`); } finally { await desktop.delete(); } ``` ## Next steps - Every call on a desktop: [Desktop](./reference/desktops). - A browser alone, driven over CDP: [browsers](./browsers). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/desktops.md. Create a Runtime desktop, take a screenshot, open https://example.com in its Chromium with act (focus the address bar, type the URL, press Return), take another screenshot and save both as PNG files. Share port 6080 with a private preview and print its url with `vnc.html?runtime_preview_token=` so I can watch it. Delete it when I say I'm done. > > This page as Markdown: https://withruntime.com/docs/desktops.md --- # Errors and retries ## The shape of an error Every error has the same fields: `code`, `message`, `requestId`, `hint`, `retryable`, `param`, `details`. Branch on `code`, never on `message`; include `requestId` when you report a problem. ```json { "error": { "code": "not_found", "message": "No such sandbox.", "requestId": "req_1d0b14e4db018fed" } } ``` A command that fails inside a sandbox is not an error: [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) returns its result with a non-zero `exitCode`. ## What the SDKs retry The SDKs send a call again, up to 3 times, on these answers: | Status | Code | Retried | | --- | --- | --- | | 429 | `rate_limited` | When the answer names its wait (`Retry-After`) | | 503 | `unavailable` | Always | | 503 | `capacity_unavailable` | Always | Every other error is returned to you. A call waits at most 60 seconds for its answer, and a retry waits at most 60 seconds. ## Make a retry safe A create takes an `Idempotency-Key` header. Sent again with the same key, it returns what the first call made instead of making another. The SDKs send one with every change and reuse it when they retry; when you retry yourself, reuse your key. ## Versions The SDKs send the `Runtime-Version` header with 2026-10-27, the version of the API they were generated from. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/errors.md. Make this project's Runtime calls branch on the error's code, never its message, send an Idempotency-Key with every create so a retry never makes a second sandbox, and log the requestId of every error. > > This page as Markdown: https://withruntime.com/docs/errors.md --- # Files | Call | What it does | | --- | --- | | [`PUT /v2/sandboxes/{id}/files`](./reference/sandboxes#write) | Writes the request's bytes to a file as they come, of any size (Content-Length required), its folders made: the file whole when they all came, or as it was. With offset, they are written into it in place. | | [`GET /v2/sandboxes/{id}/files`](./reference/sandboxes#read) | Returns a file's bytes. | | [`GET /v2/sandboxes/{id}/files/list`](./reference/sandboxes#listfiles) | Lists a directory's entries in path order, to a depth. | | [`GET /v2/sandboxes/{id}/files/stat`](./reference/sandboxes#stat) | Returns what is at a path: a file, a directory or a link, or nothing (exists false). | | [`POST /v2/sandboxes/{id}/files:rename`](./reference/sandboxes#rename) | Moves a file, a link or a directory; refused 409 when something is at its new path, unless overwrite. With sha256 or size, a file written in parts is put in place once whole: its writes ended, then only a file of that size with every byte written and whose bytes hash to it moves; refused 409 `upload_incomplete` or `checksum_mismatch`, nothing moved. | | [`POST /v2/sandboxes/{id}/files:remove`](./reference/sandboxes#remove) | Removes a file, a link or a directory (recursive for one with contents). One missing is success, removed false. | A write takes the request's body as it comes, so a file of any size is one `PUT` with its `Content-Length`: the file is replaced whole once every byte came, or left as it was. To send a large file in parts at once, or to go on after a lost connection, write each part with `offset` to a new path, then rename that path over the file with the whole file's `size` and `sha256`: once every part's write ended, the rename moves only a file of that size with every byte written and whose bytes hash to it. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const sandbox = await runtime.sandboxes.create({}); try { await runtime.sandboxes.write(sandbox.id, new TextEncoder().encode("a,b\n1,2\n"), { path: "/tmp/data/input.csv" }); await runtime.sandboxes.exec(sandbox.id, { cmd: "tail -n 1 /tmp/data/input.csv > /tmp/data/out.csv" }); const out = new TextDecoder().decode(await runtime.sandboxes.read(sandbox.id, { path: "/tmp/data/out.csv" })); console.log(out); // 1,2 if (out.trim() !== "1,2") throw new Error(out); } finally { await runtime.sandboxes.delete(sandbox.id); } ``` A listed folder gives each entry's type, size, mode and time. A sandbox's files last as long as the sandbox. To keep them after it is deleted, take a [snapshot](./snapshots). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/files.md. Move this project's files into and out of Runtime sandboxes with the files calls; a write streams, so a file of any size is one call. > > This page as Markdown: https://withruntime.com/docs/files.md --- # Functions Answer HTTP requests with one TypeScript handler that pauses when idle and resumes on the next request. A machine that answers HTTP with a handler in /app/index.ts (`export default { fetch(request) }`, as Cloudflare Workers and Vercel take one) on port 8080, reached at its preview. It pauses after 60 seconds with nothing happening, its memory kept, and a request resumes it. | Default | Value | | --- | --- | | vCPUs | 1 | | Memory | 1 GB | | Disk | 4 GB | | Image | `runtime/standard` | | Pauses when idle | After 60 seconds | A function is a machine like a [sandbox](./sandboxes): [`POST /v2/functions`](./reference/functions#create-a-function) takes the same [SandboxCreate](./reference/sandboxes#sandboxcreate), and every field overrides a default above. You pay for the CPU it uses while it answers, $0.03 per busy vCPU-hour, and nothing for CPU while it is paused. ## Deploy a handler Write the handler to `/app/index.ts`. The function serves the new file on the next request. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const fn = await runtime.functions.create(); try { await fn.files.write("/app/index.ts", `export default { fetch(request: Request) { return Response.json({ path: new URL(request.url).pathname }); }, }; `); const preview = (await runtime.previews.create(fn.id, { port: 8080 })).info; let answer = await fetch(`${preview.url}hello`, { headers: { "x-runtime-preview-token": preview.token! } }); for (let i = 0; i < 20 && answer.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); // the handler may still be loading answer = await fetch(`${preview.url}hello`, { headers: { "x-runtime-preview-token": preview.token! } }); } console.log(answer.status, await answer.text()); // 200 {"path":"/hello"} if (answer.status !== 200) throw new Error(`the function answered ${answer.status}`); } finally { await fn.delete(); } ``` A private preview needs its token in the `x-runtime-preview-token` header. Make it public with [`visibility`](./reference/previews#previewcreate) to serve anyone. See [previews](./web-app). ## Next steps - Every call on a function: [Function](./reference/functions). - Keep secrets out of the handler's code with [secrets](./secrets). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/functions.md. Deploy this project's HTTP handler as a Runtime function: write it to /app/index.ts, share port 8080 with a preview, call it once and print the answer and the preview's url. > > This page as Markdown: https://withruntime.com/docs/functions.md --- # Identity tokens Code in a sandbox can prove which sandbox it is without a stored key. Runtime signs a short-lived OpenID Connect ID token that names the sandbox, its organization, its project and its image. Your AWS or Google Cloud account trusts Runtime's issuer once, then lets a sandbox assume a role with the token. Your own API can accept it too. ## Get a token Inside a sandbox, with no API key. Every sandbox's environment has `RUNTIME_ID_TOKEN_REQUEST_URL` and `RUNTIME_ID_TOKEN_REQUEST_TOKEN`: ```bash curl -H "Authorization: Bearer $RUNTIME_ID_TOKEN_REQUEST_TOKEN" \ "$RUNTIME_ID_TOKEN_REQUEST_URL?audience=sts.amazonaws.com" ``` ```ts import { Sandbox } from "withruntime"; const { token, subject } = await Sandbox.identityToken({ audience: "sts.amazonaws.com" }); ``` ```python from withruntime import Sandbox token = Sandbox.identity_token("sts.amazonaws.com") ``` - `audience` is required: who the token is for. Use `sts.amazonaws.com` for AWS, your workload identity provider's name for Google Cloud, or your API's name. - `lifetimeSeconds` sets how long the token lasts. Ask for a fresh one when it expires. - Only a running sandbox gets a token, and only for itself: Runtime knows the sandbox by the connection it asks on, never by anything the request says. - A program started without the two variables reads them from `http://runtime.internal/v1/environment` (JSON). ## What a token says | Claim | | | --- | --- | | `iss` | `https://withruntime.com/oidc` | | `sub` | `org::image::sandbox:` | | `aud` | The audience you asked for | | `org_id`, `project_id` | The sandbox's organization and project | | `sandbox_id`, `sandbox_name` | The sandbox, and its name if it has one | | `image`, `image_id` | The image's name (`base` for none of your own) and its id | | `funding`, `region`, `runtime_environment` | `paid`, where it runs, and `production` | | `iat`, `nbf`, `exp`, `jti` | When it was issued, from when and until when it holds, and its own id | A trust policy matches on `sub`: `org::*` is every sandbox of an organization, and `org::image::*` every sandbox made from one image. ## Trust Runtime in AWS Add an OpenID Connect identity provider with the provider URL `https://withruntime.com/oidc` and the audience `sts.amazonaws.com`. Give a role this trust policy: ```json { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/withruntime.com/oidc" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "withruntime.com/oidc:aud": "sts.amazonaws.com" }, "StringLike": { "withruntime.com/oidc:sub": "org::*" } } } ``` In the sandbox, write the token to a file and set `AWS_WEB_IDENTITY_TOKEN_FILE` and `AWS_ROLE_ARN`: every AWS SDK and the CLI then assume the role by themselves. ## Trust Runtime in Google Cloud Create a workload identity pool with an OIDC provider: issuer `https://withruntime.com/oidc`, attribute mapping `google.subject=assertion.sub` and `attribute.org_id=assertion.org_id`, and an attribute condition such as `assertion.org_id == ''`. Use the provider's full name as the audience, and exchange the token at Google's Security Token Service. ## Check a token in your own API The issuer's discovery document is `https://withruntime.com/oidc/.well-known/openid-configuration` and its keys are at `https://withruntime.com/oidc/jwks`. Check the RS256 signature with the key its `kid` names, then `iss`, `aud` and `exp`, as any JWT library does. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/identity-tokens.md. Replace every cloud access key this project's sandboxed code holds with an identity token: trust Runtime's issuer once in the cloud account, give the role a trust policy that names this organization's sandboxes, and get credentials from the token in the sandbox. > > This page as Markdown: https://withruntime.com/docs/identity-tokens.md --- # Images and builds An image is the disk a machine boots: [`POST /v2/images`](./reference/images#create-a-image) makes one, and [`image`](./reference/sandboxes#sandboxcreate) boots any product from it. A build runs on a machine of its own: The machine an image's build runs on: Docker's own builder (BuildKit), its run `runtime-image-build`, deleted once its image is made. Made by an image's create, and billed as any machine is, for the CPU it uses and the memory it holds while it builds. | Build machine | Value | | --- | --- | | vCPUs | 2 | | Memory | 4 GB | | Disk | 16 GB | [`POST /v2/images`](./reference/images#create-a-image) takes one source: | Field | What it builds | | --- | --- | | [`recipe`](./reference/images#imagecreate) | Packages, files and commands, rendered into a Dockerfile. Not with `files` or `context`. | | [`dockerfile`](./reference/images#imagecreate) | A Dockerfile: multi-stage builds, `ARG`, `COPY --from`, heredocs. `COPY` reads `files`. | | [`image`](./reference/images#imagecreate) | An OCI image to use as it is, from a public registry: `python:3.12-slim`, `ghcr.io/org/app:1`. | ## Build an image and boot from it ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const image = await runtime.images.create({ name: `example-${Date.now()}`, recipe: { pip: ["cowsay"] } }); let sandbox; try { for (let i = 0; i < 400 && image.info.state !== "ready"; i++) { if (image.info.state === "failed") throw new Error(JSON.stringify(image.info)); await new Promise((r) => setTimeout(r, 250)); await image.refresh(); } sandbox = await runtime.sandboxes.create({ image: image.id }); const said = await sandbox.exec(["python3", "-m", "cowsay", "-t", "built"]); console.log(said.stdout); if (!said.stdout.includes("built")) throw new Error(said.stderr); } finally { await sandbox?.delete(); await image.delete(); } ``` Read a build's output with [`GET /v2/images/{id}/logs`](./reference/images#logs). Each build of the same [`name`](./reference/images#imagecreate) is its next version; boot `name:version` to pin one. ## Next steps - Every call on an image: [Image](./reference/images). - Keep a running machine's memory and disk instead: [snapshots](./snapshots). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/images.md. Build a Runtime image for this project with its system and language packages (a recipe, or its Dockerfile), wait until it is ready, then create a sandbox from it and run the project's tests there. > > This page as Markdown: https://withruntime.com/docs/images.md --- # Jobs A job runs its command on a schedule: each run boots a fresh machine, runs [`run`](./reference/jobs#jobsettings) to its end, and is billed for that time alone. [`POST /v2/jobs`](./reference/jobs#create-a-job) takes a [JobCreate](./reference/jobs#jobcreate): | Field | What it sets | | --- | --- | | [`schedule`](./reference/jobs#jobsettings) | When it runs. A cron line with [`cron`](./reference/jobs#jobschedule) and [`timezone`](./reference/jobs#jobschedule), or one time with [`at`](./reference/jobs#jobschedule). | | [`run`](./reference/jobs#jobsettings) | The command each run runs; the run ends when it ends. | | [`retry`](./reference/jobs#jobsettings) | How a failed run is run again; never when omitted. | | [`secrets`](./reference/jobs#jobsettings) | Which of its org's secrets each run gets; every one whose scope admits it when omitted. | | [`maxCost`](./reference/jobs#jobsettings) | The most one run may cost, in US dollars (`"0.50"`): a run pauses once it has cost that, as a machine at its maxCost does. | ## Schedule a job and run it now ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const job = await runtime.jobs.create({ name: `nightly-${Date.now()}`, schedule: { cron: "0 3 * * *", timezone: "America/Denver" }, run: { cmd: ["python3", "-c", "print(sum([125, 250, 375]))"] }, }); try { await job.run(); let run; for (let i = 0; i < 240 && !run?.endedAt; i++) { await new Promise((r) => setTimeout(r, 250)); for await (const each of runtime.jobRuns.list({ job: job.id })) run = each; } const output = await runtime.jobRuns.output(run!.id); console.log(run!.exitCode, JSON.stringify(output).slice(0, 200)); // 0 ... 750 if (run!.exitCode !== 0) throw new Error(JSON.stringify(run)); } finally { await job.delete(); } ``` [`POST /v2/jobs/{id}:pause`](./reference/jobs#pause) stops its schedule and [`POST /v2/jobs/{id}:resume`](./reference/jobs#resume) starts it again. [`GET /v2/job-runs`](./reference/job-runs#list-jobruns) lists every run of a job. ## Next steps - Every call on a job: [Job](./reference/jobs). - Run a repository's checks instead: [CI](./ci). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/jobs.md. Turn this project's scheduled task into a Runtime job: create it with its cron schedule, timezone and command, run it once now, and print that run's exit code and output. > > This page as Markdown: https://withruntime.com/docs/jobs.md --- # API keys and access Every call sends an API key as a bearer token: ```bash curl https://api.withruntime.com/v2/me -H "Authorization: Bearer $RUNTIME_API_KEY" ``` The SDKs, the CLI and the MCP server read the key from `RUNTIME_API_KEY`. The base URL is https://api.withruntime.com; set `RUNTIME_API_URL` to call another. ## Keys - [`POST /v2/keys`](./reference/keys#create-a-key) makes a key. Its secret is returned once: store it in your secret manager. - [`GET /v2/keys`](./reference/keys#list-keys) lists the organization's keys (every key for an owner or an admin, the caller's own otherwise), and [`DELETE /v2/keys/{id}`](./reference/keys#delete-a-key) revokes one at once. - [`GET /v2/me`](./reference/me#get-a-me) returns who the key is: the agent it acts as, its organization, project and role. Every key may call it. A key acts only with the actions its holder's grant allows, in one project when made with `projectId` (Growth and up), otherwise in every project its holder reaches. Each call's action is named on its reference page, such as `sandboxes:create` for [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox). Give a worker that only runs code a key without `sandboxes:delete`, and a dashboard a key that only reads. ## Inside a sandbox Never put a Runtime key in a sandbox that runs code you don't trust. To let that code call another API, use a [secret](./secrets). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/keys.md. Give this project its own Runtime API key with only the actions its code calls, store it as RUNTIME_API_KEY in its secret manager, and never write the key into code, logs or a sandbox. > > This page as Markdown: https://withruntime.com/docs/keys.md --- # Sandbox lifecycle A sandbox's [`state`](./reference/sandboxes#sandbox) is one of `starting`, `running`, `paused`, `deleted`, `error`. Every change of state is one of the moves below: a call you make, or Runtime's own when the machine starts, stops or is lost. | From | To | By | | --- | --- | --- | | (new) | `starting` | [`create`](./reference/sandboxes#create-a-sandbox) | | `starting` | `running` | Runtime | | `starting` | `error` | Runtime | | `running`, `starting` | `paused` | [`pause`](./reference/sandboxes#pause) | | `running` | `paused` | Runtime | | `paused` | `starting` | [`resume`](./reference/sandboxes#resume) | | `running` | `starting` | Runtime | | `starting`, `running`, `paused`, `error` | `deleted` | [`delete`](./reference/sandboxes#delete-a-sandbox) | ## What to do in each state - [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) resumes a `paused` sandbox first, so a paused sandbox needs no resume call before a command. - [`POST /v2/sandboxes/{id}:pause`](./reference/sandboxes#pause) keeps the sandbox's disk and stops its CPU and memory billing. [`POST /v2/sandboxes/{id}:resume`](./reference/sandboxes#resume) starts it again. See [pause and resume](./pause-and-resume). - [`DELETE /v2/sandboxes/{id}`](./reference/sandboxes#delete-a-sandbox) ends a sandbox in any state. Delete every sandbox you no longer need: a paused sandbox still pays for its storage. - A `error` sandbox failed to start and can only be deleted. Create a new one, from a [snapshot](./snapshots) if you keep its state. - A `starting` sandbox is being made, resumed, or started again on another server after its own stopped answering; wait for `running`. - A `deleted` sandbox is in a delete's answer alone: a get of a deleted sandbox is 404, and no list shows one. ## No time limit A sandbox has no time limit: it runs until it pauses or is deleted. [`idlePauseSeconds`](./reference/sandboxes#sandbox): Seconds with nothing happening before it pauses; 0 never. ## Spending limits [`maxCost`](./reference/sandboxes#sandboxcreate): The most it may cost in all, in US dollars (`"5.00"`): once it has cost that it pauses, and starts again only once its maxCost is raised (`update`); what a key's per-request and spend caps count. When omitted under a key with a per-request or spend cap, the most that key's caps leave. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/lifecycle.md. Check this project's Runtime code handles every sandbox state it can meet, and that every sandbox it creates is deleted on every path, failures included. > > This page as Markdown: https://withruntime.com/docs/lifecycle.md --- # Limits Your plan sets how much runs at once. [`GET /v2/usage`](./reference/usage#get-a-usage) returns your account's limits as they apply now, with its credit and charges. | Limit | Pro | Growth | Scale | | --- | --- | --- | --- | | vCPUs in one sandbox | 8 | 16 | 32 | | Memory in one sandbox (GiB) | 32 | 64 | 96 | | vCPUs running at once | 100 | 250 | 500 | | Memory running at once (GiB) | 200 | 500 | 1024 | | New sandboxes a second | 20 | 50 | 100 | | Disk, all sandboxes (GiB) | 500 | 2048 | 5120 | During the trial, at most 5 new sandboxes start each second. Enterprise sets its own limits. Every limit is in the [pricing reference](./reference/pricing). ## When a limit is reached A create past a limit is refused with an error that names the limit. Pausing or deleting sandboxes frees their vCPUs and memory. The SDKs retry an answer that names its wait; see [errors and retries](./errors). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/limits.md. Check this project never asks for a sandbox larger than its plan allows or runs more at once than its limit, and that it handles a refusal by waiting or queueing rather than failing the user's task. > > This page as Markdown: https://withruntime.com/docs/limits.md --- # MCP Runtime serves two MCP servers over streamable HTTP: | Server | Address | Key | | --- | --- | --- | | Runtime's tools | https://api.withruntime.com/mcp | Your API key, as a bearer token | | Runtime's docs | https://api.withruntime.com/mcp/docs | None | The tools are the API's calls, generated from the same spec: for example `runtime_sandboxes_create`, `runtime_sandboxes_exec` and `runtime_sandboxes_previews_create`. The docs server serves the API reference as Markdown, with `search_runtime_docs`, `read_runtime_doc` and `list_runtime_docs`. ## Add them to your agent Claude Code: ```bash claude mcp add --transport http runtime https://api.withruntime.com/mcp --header "Authorization: Bearer $RUNTIME_API_KEY" claude mcp add --transport http runtime-docs https://api.withruntime.com/mcp/docs ``` Other clients take the same addresses. For a client that only runs local servers, add the tools over stdio with `npx -y withruntime mcp`. ## Docs for agents Every page of these docs is also Markdown at its address with `.md` added, and [llms.txt](https://withruntime.com/llms.txt) lists them all. Each guide ends with a prompt to give your agent. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/mcp.md. Add Runtime's MCP server and its docs server to my agent's configuration, with the key from RUNTIME_API_KEY, then list the tools you have and create, use and delete one sandbox to show they work. > > This page as Markdown: https://withruntime.com/docs/mcp.md --- # Networking ## Connections out By default a sandbox can connect to the internet. [`PUT /v2/sandboxes/{id}/network`](./reference/sandboxes#setnetwork) replaces its rules with a [NetworkRules](./reference/sandboxes#networkrules): Replaces where a sandbox may connect out, for its next connection and within a second for its open ones: those the new rules refuse are cut. - [`allowOutbound`](./reference/sandboxes#networkrules): The only places it may reach, each a host, `*.` and a name for every name under it, an address or a CIDR (`[` and `]` around an IPv6 address), every port when it names none; `:port` for that port alone, on a host name for a port beyond 80 and 443, which go together. `*` is every public host. Every public host when omitted; nothing when empty. - [`denyOutbound`](./reference/sandboxes#networkrules): Places it may never reach, written as in allowOutbound with no port: a deny wins over every allow. - [`GET /v2/sandboxes/{id}/network`](./reference/sandboxes#getnetwork) returns the rules in force. ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const sandbox = await runtime.sandboxes.create({}); try { await runtime.sandboxes.setNetwork(sandbox.id, { allowOutbound: ["pypi.org"] }); const probe = (url: string) => runtime.sandboxes.exec(sandbox.id, { cmd: ["curl", "-s", "-o", "/dev/null", "-m", "5", "-w", "%{http_code}", url] }); const allowed = await probe("https://pypi.org/simple/"); const refused = await probe("https://example.com/"); console.log("pypi.org:", allowed.stdout, "example.com:", refused.stdout || `refused (exit ${refused.exitCode})`); if (allowed.stdout !== "200" || refused.stdout === "200") throw new Error("the rules were not applied"); } finally { await runtime.sandboxes.delete(sandbox.id); } ``` Traffic out of a sandbox costs $0.03 per GB. Traffic in is free. ## Connections in - HTTPS: a [preview](./web-app) shares one port at an HTTPS address, private by default. - TCP: [`POST /v2/ports`](./reference/ports#create-a-port) opens a public TCP port to a sandbox. To call an API from a sandbox without giving it the key, use a [secret](./secrets). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/networking.md. Give this project's sandboxes network rules that allow only the hosts its code needs, and confirm a connection to any other host is refused. > > This page as Markdown: https://withruntime.com/docs/networking.md --- # Notebooks JupyterLab with NumPy, pandas and matplotlib, its kernels kept in memory while it is paused. A machine running JupyterLab on port 8888 over /workspace, with NumPy, pandas and matplotlib, reached at its private preview. It pauses after 300 seconds with nothing happening, its kernels kept in memory, and a visit resumes it where it was. | Default | Value | | --- | --- | | vCPUs | 2 | | Memory | 4 GB | | Disk | 4 GB | | Image | `runtime/notebooks` | | Pauses when idle | After 300 seconds | [`POST /v2/notebooks`](./reference/notebooks#create-a-notebook) takes the same [SandboxCreate](./reference/sandboxes#sandboxcreate) as a [sandbox](./sandboxes); every field overrides a default above. ## Open JupyterLab and run code ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const notebook = await runtime.notebooks.create(); try { const sum = await notebook.exec(["python3", "-c", "import pandas as pd; print(pd.Series([125, 250, 375]).sum())"]); console.log(sum.stdout); // 750 const preview = (await runtime.previews.create(notebook.id, { port: 8888 })).info; const open = () => fetch(`${preview.url}lab`, { headers: { "x-runtime-preview-token": preview.token! } }); let page = await open(); for (let i = 0; i < 60 && page.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); page = await open(); } console.log(page.status); // open the address in a browser for JupyterLab if (sum.stdout.trim() !== "750" || page.status !== 200) throw new Error(`${sum.stderr} ${page.status}`); } finally { await notebook.delete(); } ``` ## Next steps - Every call on a notebook: [Notebook](./reference/notebooks). - Run code an AI model writes, one call at a time: [run an agent's code](./agent-loop). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/notebooks.md. Create a Runtime notebook, upload this project's data to /workspace, share port 8888 with a private preview and print its url with `?runtime_preview_token=` so I can open JupyterLab. > > This page as Markdown: https://withruntime.com/docs/notebooks.md --- # Pause and resume A paused sandbox keeps its disk, its memory and its running processes, and costs only its storage, $0.18 per GB-month. Resume it and its programs carry on from where they were. - [`POST /v2/sandboxes/{id}:pause`](./reference/sandboxes#pause) pauses it. - [`POST /v2/sandboxes/{id}:resume`](./reference/sandboxes#resume) resumes it. Any call that needs it running, such as [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec), resumes it first, so you rarely call resume yourself. - A sandbox with nothing happening in it pauses by itself. Set how long it waits with [`idlePauseSeconds`](./reference/sandboxes#machineupdate) on [`POST /v2/sandboxes/{id}:update`](./reference/sandboxes#update): Seconds with nothing happening before it pauses, 60 to 86400; 0 never. ## A process keeps running across a pause ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const sandbox = await runtime.sandboxes.create({}); try { const counter = await runtime.sandboxes.exec(sandbox.id, { cmd: ["sleep", "600"], wait: false }); await runtime.sandboxes.pause(sandbox.id); await runtime.sandboxes.resume(sandbox.id); const after = (await runtime.sandboxes.processOutput(sandbox.id, counter.id)).process; console.log("after the resume, the process is", after?.state); // running if (after?.state !== "running") throw new Error(`the process is ${after?.state}`); } finally { await runtime.sandboxes.delete(sandbox.id); } ``` ## When to pause - An agent waiting on a model or a person: pause it, and the next call resumes it. - A dev environment overnight: pause it rather than delete it, and keep its installed packages and open files. - Many short tasks from the same prepared state: keep one sandbox ready and [fork](./snapshots) it for each task. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/pause-and-resume.md. Change this project so sandboxes that wait for a user or a model are paused instead of kept running or recreated, and are resumed by the next call. > > This page as Markdown: https://withruntime.com/docs/pause-and-resume.md --- # Pricing You pay for what your sandboxes use, measured, plus a plan fee that comes back as usage. Every figure on this page comes from the [pricing reference](./reference/pricing), which billing charges from. ## What a sandbox costs | While it is | You pay for | Price | | --- | --- | --- | | Running | CPU it uses | $0.03 per busy vCPU-hour | | Running | Memory it holds | $0.008 per GB-hour | | Running | Its disk | $0.10 per GB-month | | Paused | What it stores | $0.18 per GB-month | | Any | Traffic it sends out | $0.03 per GB | - **CPU is billed on use.** A sandbox waiting on a model or a network call uses almost no CPU, and pays almost nothing for it. While it runs, it is billed at least 0.1 vCPU. - **Memory is billed on what the sandbox holds**, its [`memoryGB`](./reference/sandboxes#sandboxcreate), while it runs. - **A paused sandbox pays only for storage.** See [pause and resume](./pause-and-resume). - **A deleted sandbox costs nothing.** - **No traffic out is free.** Every GB a sandbox sends out is billed at $0.03 per GB, from the plan's included usage like every other charge. Traffic in is free. So the cost of a sandbox is about: busy vCPUs × hours × $0.03, plus GB of memory × hours × $0.008. ## Plans | | Pro | Growth | Scale | | --- | --- | --- | --- | | Monthly fee | $25 | $99 | $499 | | Usage included each month | $25 | $110 | $575 | | vCPUs running at once | 100 | 250 | 500 | | vCPUs in one sandbox | 8 | 16 | 32 | The fee is returned as usage: on Pro, the first $25 of usage each month is included. Enterprise is yearly, with custom limits. Every plan's limits are in the [pricing reference](./reference/pricing). ## Trial Signing up takes no card. Your first sandbox asks for one, and the 7-day Pro trial with $5 of usage starts then. ## Control what you spend - [`maxCost`](./reference/sandboxes#sandboxcreate): The most it may cost in all, in US dollars (`"5.00"`): once it has cost that it pauses, and starts again only once its maxCost is raised (`update`); what a key's per-request and spend caps count. When omitted under a key with a per-request or spend cap, the most that key's caps leave. - [`GET /v2/usage`](./reference/usage#get-a-usage) returns the month's usage so far. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/pricing.md and https://withruntime.com/docs/reference/pricing.md, then estimate this project's monthly Runtime bill from how many sandboxes it runs, their size, how long they run and how busy their CPU is. Show the arithmetic. > > This page as Markdown: https://withruntime.com/docs/pricing.md --- # Products Every product is a Linux machine with its own kernel, disk and network: a Firecracker microVM. They share one API, so a call you learn on one works on all of them. Each product starts at its own defaults, runs its own program, and serves its own port. Any field of [SandboxCreate](./reference/sandboxes#sandboxcreate) overrides a default. | Product | What it is | vCPUs | Memory | Disk | Pauses when idle | | --- | --- | --- | --- | --- | --- | | [Sandboxes](./sandboxes) | A Linux machine with its own kernel. | 2 | 4 GB | 4 GB | After 300 seconds | | [Functions](./functions) | A machine that answers HTTP with a handler in /app/index.ts. | 1 | 1 GB | 4 GB | After 60 seconds | | [Apps](./apps) | A machine that keeps a web app in /app running on port 8080. | 2 | 2 GB | 4 GB | Never | | [Sites](./sites) | A machine that serves the static files in /site on port 8080. | 1 | 1 GB | 4 GB | After 60 seconds | | [CI/CD](./ci) | A machine that runs a repository's checks to their end. | 4 | 16 GB | 16 GB | After 300 seconds | | [Browsers](./browsers) | A machine running headless Chromium. | 2 | 4 GB | 4 GB | After 60 seconds | | [Desktops](./desktops) | A machine running a Linux desktop with Chromium. | 2 | 4 GB | 4 GB | After 300 seconds | | [Notebooks](./notebooks) | A machine running JupyterLab on port 8888 over /workspace. | 2 | 4 GB | 4 GB | After 300 seconds | | [Dev environments](./workspaces) | A development environment. | 4 | 8 GB | 16 GB | After 30 minutes | | [Containers](./containers) | A machine that runs one OCI image from any registry under Docker on its own network. | 1 | 1 GB | 4 GB | After 300 seconds | | [Builds](./images) | The machine an image's build runs on. | 2 | 4 GB | 16 GB | Never | Each machine is billed for the CPU it uses, $0.03 per busy vCPU-hour, and the memory it holds, $0.008 per GB-hour. A paused machine is billed only for what it stores. [Jobs](./jobs) run a command on a schedule, each run on a fresh machine. [Images](./images) are the disks machines boot. ## What every product does - Run commands and programs: [commands and processes](./commands). - Read and write its files: [files](./files). - Share a port at an HTTPS address: [previews](./web-app). - Pause it and resume it where it was: [pause and resume](./pause-and-resume). - Copy it, running, with its memory: [snapshots and forks](./snapshots). - Control where it connects: [networking](./networking). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/products.md. Tell me which Runtime products this project should use for each part of it (its agent's code, its web app, its checks, its scheduled tasks), and why. > > This page as Markdown: https://withruntime.com/docs/products.md --- # Sandboxes A sandbox is a Linux machine of your own: a Firecracker microVM with its own kernel, memory, disk and network address. Code in one sandbox can't see another sandbox or the server it runs on. A sandbox is the right place for code you don't fully trust, such as code an AI model wrote or a customer uploaded. ## What you choose at create [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox) takes a [SandboxCreate](./reference/sandboxes#sandboxcreate). Every field is optional: | Field | What it sets | | --- | --- | | [`vcpu`](./reference/sandboxes#sandboxcreate) | Its vCPUs. | | [`memoryGB`](./reference/sandboxes#sandboxcreate) | Its memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (`1.5`). | | [`diskGB`](./reference/sandboxes#sandboxcreate) | Its disk in GB (1 GB is 1,024 MiB), to the MiB. | | [`image`](./reference/sandboxes#sandboxcreate) | The image it boots, by name (its newest version), `name:version` or ID; Runtime's default image when omitted. | | [`snapshot`](./reference/sandboxes#sandboxcreate) | A snapshot it starts as: a copy of it running, at its sizes, in its project, with its secrets. | | [`name`](./reference/sandboxes#sandboxcreate) | Its name, unique in its project. | | [`labels`](./reference/sandboxes#sandboxcreate) | Labels to find it by. | | [`secrets`](./reference/sandboxes#sandboxcreate) | The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. | | [`maxCost`](./reference/sandboxes#sandboxcreate) | The most it may cost in all, in US dollars (`"5.00"`): once it has cost that it pauses, and starts again only once its maxCost is raised (`update`); what a key's per-request and spend caps count. When omitted under a key with a per-request or spend cap, the most that key's caps leave. | On the Pro plan, one sandbox has at most 8 vCPUs and 32 GiB of memory, and the account runs at most 100 vCPUs at once. See [limits](./limits). ## What runs in it The default image is a Linux system with Python and Node.js. Commands run as the user `runtime` in `/workspace`, with `sudo` and no password. Install anything with the system's package manager, or start from your own [image or snapshot](./snapshots). - Run commands with [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec), and long-running programs with it too, with [`wait`](./reference/sandboxes#execrequest) false. See [commands and processes](./commands). - Read and write files with [`GET /v2/sandboxes/{id}/files`](./reference/sandboxes#read) and [`PUT /v2/sandboxes/{id}/files`](./reference/sandboxes#write). See [files](./files). - Share a port at an HTTPS address with [`POST /v2/sandboxes/{id}/previews`](./reference/previews#create-a-preview). See [previews](./web-app). ## What it costs A running sandbox is billed for the CPU it uses, $0.03 per busy vCPU-hour, at least 0.1 vCPU while it runs, and for the memory it holds, $0.008 per GB-hour. Its disk is $0.10 per GB-month while it runs. A paused sandbox is billed only for what it stores, $0.18 per GB-month. See [pricing](./pricing). ## Find your sandboxes [`GET /v2/sandboxes`](./reference/sandboxes#list-sandboxes) returns the project's sandboxes, newest first. Filter it by state or by label. [`GET /v2/sandboxes/{id}`](./reference/sandboxes#get-a-sandbox) returns one, by ID. A sandbox's [`state`](./reference/sandboxes#sandbox) is one of `starting`, `running`, `paused`, `deleted`, `error`; see [lifecycle](./lifecycle). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/sandboxes.md and https://withruntime.com/docs/lifecycle.md, then explain to me how this project should use Runtime sandboxes: one per task or per user, what size, and when each is deleted. > > This page as Markdown: https://withruntime.com/docs/sandboxes.md --- # SDKs and the CLI Every SDK, the CLI and the MCP tools are generated from the same spec as the API, so each one has every call, with the same names and fields. Each call's page in the [API reference](./reference/overview) shows it in curl, TypeScript, Python, Ruby, the CLI and MCP. | | Install | Client | | --- | --- | --- | | TypeScript and JavaScript | `npm install withruntime` | `new Runtime()` | | Python | `pip install withruntime` | `Runtime()` | | Ruby | `gem install withruntime` | `Withruntime::Generated::Kit.new` | | Go | `go get withruntime.com/go` | `generated.New(generated.Options{})` | | CLI | `npm install --global withruntime` | `runtime ` | Each client reads `RUNTIME_API_KEY` and, when it is set, `RUNTIME_API_URL`. A call's method is named for it: [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) is `runtime.sandboxes.exec` in TypeScript, `runtime.sandboxes.exec` in Python and `runtime sandboxes exec` in the CLI. ## Retries and timeouts The SDKs retry the answers [errors and retries](./errors) lists, up to 3 times, with the same `Idempotency-Key`, so a retried create never makes a second sandbox. ## From an agent An agent can call the same API through MCP. See [MCP](./mcp). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/sdks.md. Install the Runtime SDK for this project's language, call it with the key from RUNTIME_API_KEY, and use the reference's example for each call you need. > > This page as Markdown: https://withruntime.com/docs/sdks.md --- # Secrets Code in a sandbox, such as an agent's, should never hold your API keys: anything it can read, it can leak. A secret keeps the key outside the sandbox. The sandbox holds a placeholder, and Runtime puts the real value in the request as it leaves for the hosts you name, over HTTPS. ## Store a secret [`PUT /v2/secrets/{name}`](./reference/secrets#set) takes a [SecretSet](./reference/secrets#secretset): | Field | | | --- | --- | | [`value`](./reference/secrets#secretset) | Its value, never answered. Hidden: 1 to 8192 visible ASCII characters and spaces, one line, since it goes into an HTTP header. Visible: 1 byte to 64 KiB of UTF-8 text with no NUL, newlines included (a PEM file, an SSH key, a service account's JSON). With it, the set stores the secret whole, as its fields say. Without it, the set changes only the hosts, `policies.rules` and scope it names, and keeps the rest: hosts and rules only narrow, since widening needs the value, and so does a visible secret's scope, whose machines hold its value; any other field is refused 400. | | [`hosts`](./reference/secrets#secretset) | The hosts its value goes to on HTTPS: a name, or `*.` and a name for every name under it. Required unless visible; refused when visible. | | [`header`](./reference/secrets#secretset) | The header it is set in on every request to its hosts; when omitted, its placeholder is replaced in the credential headers (Authorization, x-api-key and the like). Hidden secrets only. | | [`format`](./reference/secrets#secretset) | The header's value, `{value}` replaced by the secret; `{value}` when omitted. Hidden secrets only. | | [`envName`](./reference/secrets#secretset) | The environment variable that holds its placeholder (or, when visible, its value) in each machine it reaches; its name when omitted. When two secrets that reach one machine name the same variable, it holds the one first by name. | | [`scope`](./reference/secrets#secretset) | The machines that may use it; every machine of the organization when omitted. | The answer, a [Secret](./reference/secrets#secret), never holds the value: [`placeholder`](./reference/secrets#secret) is what a sandbox holds in its place. ```bash curl -X PUT https://api.withruntime.com/v2/secrets/OPENAI_API_KEY \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{"value": "sk-...", "hosts": ["api.openai.com"], "scope": {"labelsAny": [{"team": "agents"}]}}' ``` ## Which sandboxes get it - Scope every secret. When [`scope`](./reference/secrets#secretset) is left out, The machines that may use it; every machine of the organization when omitted. Scope a secret to the labels of the sandboxes that need it: Machines with every label of any one of these sets. - A sandbox can narrow what it gets further at create: [`secrets`](./reference/sandboxes#sandboxcreate): The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. - [`PUT /v2/secrets/{name}`](./reference/secrets#set) without the value changes a stored secret's hosts, rules or scope and keeps the rest: hosts and rules only narrow, since widening needs the value. - [`DELETE /v2/secrets/{name}`](./reference/secrets#delete-a-secret) removes it. Sandboxes that held its placeholder can no longer use it. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/secrets.md. Store each API key this project's sandboxed code uses as a Runtime secret for the hosts it calls, scope each to the sandboxes that need it, and remove the keys from the sandboxes' environment and files. > > This page as Markdown: https://withruntime.com/docs/secrets.md --- # Sites Serve a folder of static files at an HTTPS address, paused when nobody visits. A machine that serves the static files in /site on port 8080 (as Netlify and Vercel serve a build's output), reached at its preview. It pauses after 60 seconds with nothing happening, its memory kept, and a visit resumes it. | Default | Value | | --- | --- | | vCPUs | 1 | | Memory | 1 GB | | Disk | 4 GB | | Image | `runtime/sites` | | Pauses when idle | After 60 seconds | [`POST /v2/sites`](./reference/sites#create-a-site) takes the same [SandboxCreate](./reference/sandboxes#sandboxcreate) as a [sandbox](./sandboxes); every field overrides a default above. ## Publish a page Write files under `/site`. Upload a whole build folder at once with [`PUT /v2/sites/{id}/files/archive`](./reference/sites#uploadfolder). ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const site = await runtime.sites.create(); try { await site.exec("sudo install -d -o runtime /site"); await site.files.write("/site/index.html", "

Hello from a Runtime site

\n"); const preview = (await runtime.previews.create(site.id, { port: 8080 })).info; const open = () => fetch(preview.url, { headers: { "x-runtime-preview-token": preview.token! } }); let page = await open(); for (let i = 0; i < 20 && page.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); page = await open(); } console.log(page.status, await page.text()); if (page.status !== 200) throw new Error(`the site answered ${page.status}`); } finally { await site.delete(); } ``` To serve it to anyone, make the preview public with [`visibility`](./reference/previews#previewcreate) "public": a public preview needs an account with a kept top-up, and needs no token. Serve it at your own domain with [`POST /v2/domains`](./reference/domains#create-a-domain) ([networking](./networking)). ## Next steps - Every call on a site: [Site](./reference/sites). - A server that renders pages instead: [apps](./apps). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/sites.md. Build this project's static site, upload its output folder to a Runtime site's /site, share port 8080 with a preview and print its url with `?runtime_preview_token=` so I can open it. > > This page as Markdown: https://withruntime.com/docs/sites.md --- # Snapshots, forks and images Installing the same packages in every new sandbox is slow. Prepare a sandbox once, then start from it. | Call | What it does | | --- | --- | | [`POST /v2/sandboxes/{id}:snapshot`](./reference/sandboxes#snapshot) | Keeps a sandbox's memory and disk as they are now, a snapshot to start sandboxes from; with `image`, its disk alone as that image's next version. The sandbox runs on. Asked again with the same Idempotency-Key, it returns the same snapshot. | | [`POST /v2/sandboxes/{id}:fork`](./reference/sandboxes#fork) | Copies a sandbox as it is now, memory and disk, into `count` copies of its own, each running on its host. Asked again with the same Idempotency-Key, it returns the same copies. | | [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox) with [`snapshot`](./reference/sandboxes#sandboxcreate) | A snapshot it starts as: a copy of it running, at its sizes, in its project, with its secrets. | | [`GET /v2/snapshots`](./reference/snapshots#list-snapshots), [`GET /v2/snapshots/{id}`](./reference/snapshots#get-a-snapshot), [`DELETE /v2/snapshots/{id}`](./reference/snapshots#delete-a-snapshot) | Find and delete snapshots. | | [`GET /v2/images`](./reference/images#list-images), [`GET /v2/images/{id}`](./reference/images#get-a-image) | The images a sandbox can boot, by [`image`](./reference/sandboxes#sandboxcreate). | ## Start from a snapshot ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const base = await runtime.sandboxes.create({}); let snapshotId: string | undefined; let copyId: string | undefined; try { await runtime.sandboxes.exec(base.id, { cmd: "echo prepared > /workspace/state" }); const snapshot = await runtime.sandboxes.snapshot(base.id, { name: `example-${Date.now()}` }); snapshotId = snapshot.id; const copy = await runtime.sandboxes.create({ snapshot: snapshot.id }); copyId = copy.id; const state = await runtime.sandboxes.exec(copy.id, { cmd: ["cat", "/workspace/state"] }); console.log(state.stdout); // prepared if (state.stdout.trim() !== "prepared") throw new Error(state.stdout + state.stderr); } finally { if (copyId) await runtime.sandboxes.delete(copyId); await runtime.sandboxes.delete(base.id); if (snapshotId) await runtime.snapshots.delete(snapshotId); } ``` A snapshot is billed for what it stores, $0.18 per GB-month. Deleting the sandbox it came from keeps it: delete snapshots you no longer use with [`DELETE /v2/snapshots/{id}`](./reference/snapshots#delete-a-snapshot). ## Fork a running sandbox [`POST /v2/sandboxes/{id}:fork`](./reference/sandboxes#fork) copies a sandbox as it runs, with its memory and processes, into up to the number of copies [`count`](./reference/sandboxes#forkrequest) allows: How many. Use it to try several next steps of an agent from the same point, or to start many workers from one prepared sandbox. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/snapshots.md. Prepare one Runtime sandbox with this project's dependencies installed, snapshot it, and change the project to start each task's sandbox from that snapshot instead of installing again. Delete snapshots the project no longer uses. > > This page as Markdown: https://withruntime.com/docs/snapshots.md --- # Quickstart Runtime runs Linux sandboxes: each one is a microVM with its own kernel, disk and network, created in milliseconds. This page creates a sandbox, runs a program in it and deletes it. ## Before you begin 1. Create an API key on the [Keys page](https://withruntime.com/account/keys) of the console, or with [`POST /v2/keys`](./reference/keys#create-a-key). 2. Set it as `RUNTIME_API_KEY` in your environment. Every SDK, the CLI and the MCP server read it from there. 3. Install an SDK: `npm install withruntime` (Node.js 22.12 or later, or Bun) or `pip install withruntime` (Python 3.9 or later). Signing up takes no card. Your first sandbox asks for one, and the 7-day Pro trial with $5 of usage starts then. After the trial, Pro costs $25 a month, and that fee is returned as $25 of usage. See [pricing](./pricing). ## Run a program TypeScript: ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); // reads RUNTIME_API_KEY const sandbox = await runtime.sandboxes.create(); try { await sandbox.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n"); const result = await sandbox.exec("python3 /workspace/invoice.py"); console.log(result.stdout); // 750 if (result.exitCode !== 0) throw new Error(result.stderr); } finally { await sandbox.delete(); } ``` Python: ```python from withruntime.generated import Runtime runtime = Runtime() # reads RUNTIME_API_KEY sandbox = runtime.sandboxes.create() try: sandbox.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n") result = sandbox.exec("python3 /workspace/invoice.py") print(result.stdout) # 750 assert result.exit_code == 0, result.stderr finally: sandbox.delete() ``` The HTTP API, with curl: ```bash api=https://api.withruntime.com/v2 auth="Authorization: Bearer $RUNTIME_API_KEY" id=$(curl -sf -X POST "$api/sandboxes" -H "$auth" -H "Content-Type: application/json" -d '{}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])') trap 'curl -sf -X DELETE "$api/sandboxes/$id" -H "$auth" > /dev/null' EXIT curl -sf -X POST "$api/sandboxes/$id:exec" -H "$auth" -H "Content-Type: application/json" \ -d '{"cmd": ["python3", "-c", "print(sum([125, 250, 375]))"]}' ``` What each call does: - [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox) returns once the sandbox is running. Creates a sandbox. Asked again with the same Idempotency-Key, it returns the same sandbox. - [`PUT /v2/sandboxes/{id}/files`](./reference/sandboxes#write) Writes the request's bytes to a file as they come, of any size (Content-Length required), its folders made: the file whole when they all came, or as it was. With offset, they are written into it in place. - [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) Runs a command as a process and returns it once it ended, with its output; with wait false, at once, while it runs. A paused sandbox is resumed first. Asked again with the same Idempotency-Key, it runs nothing more: it returns the first run's process, waiting for its end while it runs. A command that fails is a result with a non-zero `exitCode`, never an error. - [`DELETE /v2/sandboxes/{id}`](./reference/sandboxes#delete-a-sandbox) ends the sandbox and its billing. ## Next steps - [Run an agent's code](./agent-loop): a loop that runs model-written code and feeds back its errors. - [Serve a web app](./web-app): share a port of a sandbox at an HTTPS address. - [Sandboxes](./sandboxes): what a sandbox is, and its [lifecycle](./lifecycle). - The [API reference](./reference/overview): every call, field and error. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/start.md and https://withruntime.com/llms.txt, then add Runtime to this project: create a sandbox with the SDK this project's language uses, run the project's real command in it, and delete the sandbox when the command ends. Take the API key from the RUNTIME_API_KEY environment variable and never print it. > > This page as Markdown: https://withruntime.com/docs/start.md --- # Switch from Daytona | Daytona | Runtime | | --- | --- | | `daytona.create()` | [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox) | | `sandbox.process.executeCommand(cmd)` | [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) | | `sandbox.process.createSession()`, `executeSessionCommand()` | [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) with [`wait`](./reference/sandboxes#execrequest) false, [`POST /v2/sandboxes/{id}/processes/{process}:write`](./reference/sandboxes#writeprocess), [`GET /v2/sandboxes/{id}/processes/{process}/output`](./reference/sandboxes#processoutput) | | `sandbox.fs.uploadFile()`, `downloadFile()` | [`PUT /v2/sandboxes/{id}/files`](./reference/sandboxes#write), [`GET /v2/sandboxes/{id}/files`](./reference/sandboxes#read) | | `sandbox.getPreviewLink(port)` | [`POST /v2/sandboxes/{id}/previews`](./reference/previews#create-a-preview) | | `sandbox.stop()`, `sandbox.start()` | [`POST /v2/sandboxes/{id}:pause`](./reference/sandboxes#pause), [`POST /v2/sandboxes/{id}:resume`](./reference/sandboxes#resume): memory and processes are kept | | `sandbox.delete()` | [`DELETE /v2/sandboxes/{id}`](./reference/sandboxes#delete-a-sandbox) | | Snapshots | [snapshots](./snapshots) | ```python from withruntime.generated import Runtime runtime = Runtime() sandbox = runtime.sandboxes.create() try: response = runtime.sandboxes.exec(sandbox.id, cmd="echo $((6 * 7))") print(response.stdout) # 42 assert response.exit_code == 0 and response.stdout.strip() == "42", response finally: runtime.sandboxes.delete(sandbox.id) ``` A stopped Daytona sandbox restarts with an empty memory; a paused Runtime sandbox resumes with its programs still running, and costs only its storage, $0.18 per GB-month, while paused. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/switch-from-daytona.md. Replace every Daytona call in this project with its Runtime call, on a branch, remove the Daytona SDK, run the project's tests and its real job on Runtime, and fix what fails. Never delete the Daytona account or its keys. > > This page as Markdown: https://withruntime.com/docs/switch-from-daytona.md --- # Switch from E2B Runtime's sandboxes do what E2B's do, with pause and resume that keep memory, forks of a running sandbox, and CPU billed on use ($0.03 per busy vCPU-hour). Most code moves by renaming calls. | E2B | Runtime | | --- | --- | | `Sandbox.create()` | [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox) | | `sbx.commands.run(cmd)` | [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec), which returns a non-zero `exitCode` instead of throwing | | `sbx.commands.run(cmd, { background: true })` | [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) with [`wait`](./reference/sandboxes#execrequest) false | | `sbx.files.write(path, data)` | [`PUT /v2/sandboxes/{id}/files`](./reference/sandboxes#write) | | `sbx.files.read(path)` | [`GET /v2/sandboxes/{id}/files`](./reference/sandboxes#read) | | `sbx.getHost(port)` | [`POST /v2/sandboxes/{id}/previews`](./reference/previews#create-a-preview), private by default | | `sbx.betaPause()`, `Sandbox.connect(id)` | [`POST /v2/sandboxes/{id}:pause`](./reference/sandboxes#pause), [`POST /v2/sandboxes/{id}:resume`](./reference/sandboxes#resume) | | `sbx.kill()` | [`DELETE /v2/sandboxes/{id}`](./reference/sandboxes#delete-a-sandbox) | | Templates | [snapshots](./snapshots) | ## Before and after E2B: ```ts import { Sandbox } from "e2b"; const sbx = await Sandbox.create(); await sbx.files.write("/home/user/step.py", "print(21 * 2)"); const r = await sbx.commands.run("python3 /home/user/step.py"); console.log(r.stdout); await sbx.kill(); ``` Runtime: ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const sbx = await runtime.sandboxes.create({}); try { await runtime.sandboxes.write(sbx.id, new TextEncoder().encode("print(21 * 2)"), { path: "/tmp/step.py" }); const r = await runtime.sandboxes.exec(sbx.id, { cmd: ["python3", "/tmp/step.py"] }); console.log(r.stdout); // 42 if (r.stdout.trim() !== "42") throw new Error(r.stderr); } finally { await runtime.sandboxes.delete(sbx.id); } ``` What changes besides the names: - Commands run as the user `runtime` in `/workspace`, with `sudo` and no password; there is no `/home/user`. - [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) takes the program and its arguments as a list. For a shell line, pass `["bash", "-c", line]`. - A sandbox with nothing happening pauses by itself and the next call resumes it, so there is no timeout to keep extending. See [pause and resume](./pause-and-resume). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/switch-from-e2b.md. Replace every E2B call in this project with its Runtime call, on a branch, remove the E2B SDK, run the project's tests and its real job on Runtime, and fix what fails. Never delete the E2B account or its keys. > > This page as Markdown: https://withruntime.com/docs/switch-from-e2b.md --- # Switch from AWS Lambda Lambda runs a handler per request, for at most 15 minutes, with no state between calls. A Runtime sandbox is a whole Linux machine: it keeps its files, processes and memory between calls, runs as long as you need, and pauses when nothing happens in it. | Lambda | Runtime | | --- | --- | | `CreateFunction` with a package or image | [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox) from a [snapshot](./snapshots) that holds your code | | `Invoke` | [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) | | Environment variables | [`env`](./reference/sandboxes#execrequest), and [secrets](./secrets) for keys | | Function URL | [`POST /v2/sandboxes/{id}/previews`](./reference/previews#create-a-preview) | | `DeleteFunction` | [`DELETE /v2/sandboxes/{id}`](./reference/sandboxes#delete-a-sandbox) | ```bash api=https://api.withruntime.com/v2 auth="Authorization: Bearer $RUNTIME_API_KEY" id=$(curl -sf -X POST "$api/sandboxes" -H "$auth" -H "Content-Type: application/json" -d '{}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])') trap 'curl -sf -X DELETE "$api/sandboxes/$id" -H "$auth" > /dev/null' EXIT event='{"orderId": 7, "amount": 1250}' curl -sf -X POST "$api/sandboxes/$id:exec" -H "$auth" -H "Content-Type: application/json" \ -d "{\"cmd\": [\"python3\", \"-c\", \"import json, os; e = json.loads(os.environ['EVENT']); print(e['amount'] / 100)\"], \"env\": {\"EVENT\": $(printf '%s' "$event" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}" ``` Runtime bills the CPU a sandbox uses, $0.03 per busy vCPU-hour, and the memory it holds, $0.008 per GB-hour, while it runs. Scheduled runs are [jobs](./reference/jobs). An HTTP endpoint that starts a copy per request is not on Runtime yet. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/switch-from-lambda.md. Move the code this project runs in AWS Lambda for untrusted or long-running work into Runtime sandboxes, on a branch, and run its tests and real job there. Never delete the AWS functions or their roles. > > This page as Markdown: https://withruntime.com/docs/switch-from-lambda.md --- # Switch from Modal | Modal | Runtime | | --- | --- | | `modal.Sandbox.create(app=app, image=image)` | [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox), with [`image`](./reference/sandboxes#sandboxcreate) or [`snapshot`](./reference/sandboxes#sandboxcreate) | | `sb.exec("python", "-c", code)` | [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec), with [`wait`](./reference/sandboxes#execrequest) false to read output as it comes | | `sb.open(path, "w")` | [`PUT /v2/sandboxes/{id}/files`](./reference/sandboxes#write) | | `sb.tunnels()` | [`POST /v2/sandboxes/{id}/previews`](./reference/previews#create-a-preview) | | `sb.snapshot_filesystem()` | [`POST /v2/sandboxes/{id}:snapshot`](./reference/sandboxes#snapshot) | | `sb.terminate()` | [`DELETE /v2/sandboxes/{id}`](./reference/sandboxes#delete-a-sandbox) | ```python from withruntime.generated import Runtime runtime = Runtime() sandbox = runtime.sandboxes.create() try: result = runtime.sandboxes.exec(sandbox.id, cmd=["python3", "-c", "import sys; print(sys.version_info[0])"]) print(result.stdout) # 3 assert result.stdout.strip() == "3", result finally: runtime.sandboxes.delete(sandbox.id) ``` Runtime bills the CPU a sandbox uses, $0.03 per busy vCPU-hour, and a paused sandbox pays only for storage, $0.18 per GB-month. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/switch-from-modal.md. Replace every Modal Sandbox call in this project with its Runtime call, on a branch, run the project's tests and its real job on Runtime, and fix what fails. Never delete the Modal account or its tokens. > > This page as Markdown: https://withruntime.com/docs/switch-from-modal.md --- # Switch from Vercel Sandbox | Vercel Sandbox | Runtime | | --- | --- | | `Sandbox.create({ source, ports })` | [`POST /v2/sandboxes`](./reference/sandboxes#create-a-sandbox), then write or clone your code in it | | `sandbox.runCommand(cmd, args)` | [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) | | `sandbox.runCommand({ detached: true })` | [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) with [`wait`](./reference/sandboxes#execrequest) false | | `sandbox.writeFiles(files)` | [`PUT /v2/sandboxes/{id}/files`](./reference/sandboxes#write) | | `sandbox.domain(port)` | [`POST /v2/sandboxes/{id}/previews`](./reference/previews#create-a-preview) | | `sandbox.stop()` | [`DELETE /v2/sandboxes/{id}`](./reference/sandboxes#delete-a-sandbox), or [`POST /v2/sandboxes/{id}:pause`](./reference/sandboxes#pause) to keep it | ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const sandbox = await runtime.sandboxes.create({}); try { const r = await runtime.sandboxes.exec(sandbox.id, { cmd: ["node", "-e", "console.log(process.version.startsWith('v'))"] }); console.log(r.stdout); // true if (r.stdout.trim() !== "true") throw new Error(r.stderr); } finally { await runtime.sandboxes.delete(sandbox.id); } ``` A Vercel sandbox ends at its timeout. A Runtime sandbox has no timeout: it pauses when nothing happens in it and resumes on the next call. ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/switch-from-vercel.md. Replace every Vercel Sandbox call in this project with its Runtime call, on a branch, run the project's tests and its real job on Runtime, and fix what fails. Never delete the Vercel project or its tokens. > > This page as Markdown: https://withruntime.com/docs/switch-from-vercel.md --- # Serve a web app A preview gives one port of a sandbox an HTTPS address. Use it to show an agent's work, run a dev server, or test a web app before you deploy it. ## Start a server and share its port Start the server with [`POST /v2/sandboxes/{id}:exec`](./reference/sandboxes#exec) and [`wait`](./reference/sandboxes#execrequest) false, so it keeps running after the call returns. Then share its port with [`POST /v2/sandboxes/{id}/previews`](./reference/previews#create-a-preview). ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const sandbox = await runtime.sandboxes.create(); try { const app = `require("http").createServer((req, res) => res.end("hello from " + req.url)).listen(3000);`; await sandbox.files.write("/workspace/server.js", app); await sandbox.exec(["node", "/workspace/server.js"], { wait: false }); const preview = (await runtime.previews.create(sandbox.id, { port: 3000 })).info; // A private preview needs its token, in a header (or `?runtime_preview_token=` for a browser). const open = () => fetch(preview.url, { headers: { "x-runtime-preview-token": preview.token! } }); let page = await open(); for (let i = 0; i < 20 && page.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); // the server may still be starting page = await open(); } console.log(page.status, await page.text()); if (page.status !== 200) throw new Error(`preview answered ${page.status}`); } finally { await sandbox.delete(); } ``` ## Private and public previews - [`visibility`](./reference/previews#previewcreate): `private` (default): a token is needed. `public`: anyone with the address. - [`token`](./reference/previews#preview): A token signed for this answer, for a private preview and a key that may create one: send it in the `x-runtime-preview-token` header, or open the url with `?runtime_preview_token=` in a browser. [`tokenExpiresAt`](./reference/previews#preview) says when it stops working. - [`ttlSeconds`](./reference/previews#previewcreate): The token's lifetime in seconds, from 60 until the calling key's own end (a year at most); a day when omitted, or the key's end when that is sooner. - [`embedOrigins`](./reference/previews#previewcreate): The sites that may show it in an iframe; omitted on one that exists, kept as it is; empty for any site. - [`POST /v2/previews/{name}:rotate`](./reference/previews#rotate) refuses every token issued so far. [`POST /v2/previews/{name}:sign`](./reference/previews#sign) issues a new one. - [`DELETE /v2/previews/{name}`](./reference/previews#delete-a-preview) stops sharing the port. A preview's address answers once its [`state`](./reference/previews#preview) is `ready`. Deleting the sandbox removes its previews. ## Next steps - Keep the app's files between sessions with [snapshots](./snapshots). - Expose a raw TCP port instead of HTTPS with [`POST /v2/ports`](./reference/ports#create-a-port) ([networking](./networking)). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/web-app.md. Run this project's web server in a Runtime sandbox, share its port with a private preview, and print the preview's url with its token (`?runtime_preview_token=`) so I can open it. Delete the preview and the sandbox when I say I'm done. > > This page as Markdown: https://withruntime.com/docs/web-app.md --- # Dev environments A development environment with VS Code in the browser, like Codespaces and Gitpod. A development environment: a machine running VS Code in the browser (code-server) on port 8080 over /workspace, reached at its private preview, as Codespaces and Gitpod give one. It pauses after 30 minutes with nothing happening, its memory kept. | Default | Value | | --- | --- | | vCPUs | 4 | | Memory | 8 GB | | Disk | 16 GB | | Image | `runtime/workspaces` | | Pauses when idle | After 30 minutes | [`POST /v2/workspaces`](./reference/workspaces#create-a-workspace) takes the same [SandboxCreate](./reference/sandboxes#sandboxcreate) as a [sandbox](./sandboxes); every field overrides a default above. ## Open VS Code ```ts import { Runtime } from "withruntime"; const runtime = new Runtime(); const workspace = await runtime.workspaces.create(); try { await workspace.exec("git clone --depth 1 https://github.com/withruntime/examples /workspace/examples || mkdir -p /workspace/examples"); const preview = (await runtime.previews.create(workspace.id, { port: 8080 })).info; const editor = `${preview.url}?folder=/workspace&runtime_preview_token=${preview.token}`; let page = await fetch(editor); for (let i = 0; i < 60 && page.status !== 200; i++) { await new Promise((r) => setTimeout(r, 250)); page = await fetch(editor); } console.log(page.status); // open the address in a browser for VS Code if (page.status !== 200) throw new Error(`the workspace answered ${page.status}`); } finally { await workspace.delete(); } ``` ## Next steps - Every call on a workspace: [Workspace](./reference/workspaces). - Pause it overnight and pick up where you left off: [pause and resume](./pause-and-resume). ## Give this to your agent Paste this into your coding agent: > Read https://withruntime.com/docs/workspaces.md. Create a Runtime workspace, clone this repository into /workspace, share port 8080 with a private preview and print its url with `?runtime_preview_token=` so I can open VS Code. > > This page as Markdown: https://withruntime.com/docs/workspaces.md