# How to preview apps an AI agent builds Run the agent's app in its sandbox, give its port an HTTPS preview address, and let the sandbox pause between visits and wake on the next. **On Runtime a preview that nobody is using costs nothing but storage.** With `idlePauseSeconds` the sandbox pauses when visits stop, keeping its files, memory and the running server; the next visit wakes it, usually in about half a second, behind a short "Waking up" page. While it runs, a 2 vCPU, 4 GiB sandbox costs $0.03125 an hour waiting on requests, because Runtime bills the CPU the app uses. ## The short answer Write the agent's files, start the server with `spawn`, and share the port: ```ts check import { Sandbox } from "withruntime"; const sbx = await Sandbox.create({ idlePauseSeconds: 900, labels: { project: "p-123" } }); await sbx.files.write( "/workspace/app/index.html", "

Built by the agent

", // what the agent wrote ); await sbx.spawn("python3 -m http.server 3000", { cwd: "/workspace/app" }); const preview = await sbx.previews.create(3000); console.log(preview.urlWithToken); // a one-time link for the user's browser ``` ```python check from withruntime import Sandbox sbx = Sandbox.create(idle_pause_seconds=900, labels={"project": "p-123"}) sbx.files.write("/workspace/app/index.html", "

Built by the agent

") sbx.spawn("python3 -m http.server 3000", cwd="/workspace/app") preview = sbx.previews.create(3000) print(preview["urlWithToken"]) # a one-time link for the user's browser ``` For a real project, replace the server with the project's own dev server, such as `npm run dev -- --port 3000`. A process started with `spawn` keeps running after your call returns; one started by `exec` ends with its command. ## Private or public | Visibility | Who can open it | Use it for | | ----------------- | ---------------------------------------------------------------------------------------- | --------------------------------- | | Private (default) | A request with the `x-runtime-preview-token` header, or the one-time `urlWithToken` link | The user watching the agent build | | Public | Anyone with the address | A shareable demo link | | Custom domain | Anyone, at your own hostname, proved by a DNS TXT record (paid accounts) | Publishing the finished app | Make a preview public with `previews.create(3000, { visibility: "public" })`. `previews.rotate(port)` refuses every token issued so far, and `previews.delete(port)` stops sharing. WebSockets work, which dev servers use for live reload. Preview addresses are under `runtimehost.com`, never under Runtime's own site, so an agent's app never shares an origin with your account ([security](/docs/security#network-access)). ## Start every project with the template running Installing a framework's dependencies takes the longest part of a new project. Do it once in a template sandbox, keep it as a snapshot, and start each new project from the snapshot. A snapshot keeps running processes, so the dev server is already up when the copy starts: ```ts check import { Runtime } from "withruntime"; const runtime = new Runtime(); // Once: install the template and start its dev server. const template = await runtime.sandboxes.create({ diskMiB: 8192 }); await template.files.upload("./template", "/workspace/app"); await template.exec("cd app && npm ci", { check: true, timeoutMs: 600_000 }); await template.spawn("cd app && npm run dev -- --port 3000"); const snapshot = await template.snapshot({ name: "web-template", retentionDays: 30 }); await template.stop(); // Each new project: a copy, a preview, and the agent at work. const project = await runtime.sandboxes.create({ snapshot: snapshot.id }); await project.update({ idlePauseSeconds: 900 }); const preview = await project.previews.create(3000); console.log(preview.urlWithToken); ``` ```python check from withruntime import Runtime runtime = Runtime() template = runtime.sandboxes.create(disk_mib=8192) template.files.upload("./template", "/workspace/app") template.exec("cd app && npm ci", check=True, timeout_ms=600_000) template.spawn("cd app && npm run dev -- --port 3000") snapshot = template.snapshot(name="web-template", retention_days=30) template.stop() project = runtime.sandboxes.create(snapshot=snapshot["id"]) project.update(idle_pause_seconds=900) preview = project.previews.create(3000) print(preview["urlWithToken"]) ``` To show the user two versions side by side, `fork` the project into copies, let the agent change each, and share a preview of each copy. ## Find the user's project again Name each project's sandbox, and `getOrCreate` answers the same one tomorrow, woken if it paused: ```ts check import { Sandbox } from "withruntime"; const sbx = await Sandbox.getOrCreate("project-p-123", { idlePauseSeconds: 900 }); console.log(sbx.info.reused, sbx.id); ``` ## What an app-preview product needs | Need | How Runtime covers it | | ------------------------------------ | ------------------------------------------------------------------------------------ | | An HTTPS address per app | `previews.create(port)`, private with a token by default | | Live reload | WebSockets pass through the preview | | Apps nobody is looking at | `idlePauseSeconds` pauses; a visit wakes it with a "Waking up" page | | Fast new projects | Create from a snapshot with the dev server already running | | An agent's code kept away from yours | A Firecracker microVM with its own kernel per project | | Packages the agent installs | Any public host on any port on paid accounts; ports 80 and 443 on the trial | | Publishing | Custom domains, up to 50, included on paid accounts ([networking](/docs/networking)) | | Many users at once | 100 sandboxes at once on a paid account to start | ## What it costs Take 200 projects a month. Each keeps a 2 vCPU, 4 GiB sandbox running 3 hours in all while its user works, using 0.1 of a vCPU on average, and is paused the other 717 hours of a 30-day month with 1 GB of its own disk and memory stored: ``` CPU: 200 × 3 h × 0.1 vCPU × $0.025 = $1.50 Memory: 200 × 3 h × 4 GiB × $0.0075 = $18.00 Paused: 200 × 1 GB × $0.08 × 717 h / 720 h = $15.93 Total: $35.43 ``` That is about 18 cents a project a month. Runtime charges $0.025 per vCPU-hour of measured CPU, $0.0075 per GiB-hour of memory while running, and $0.08 per GB per 30-day month while paused ([pricing](/docs/pricing)). The snapshot is storage at the same $0.08 rate. New accounts get 50 free sandbox hours, no card. ## Start ```bash no-run npx withruntime sandbox run --trial --keep -- python3 --version ``` The first run prints a link to approve in your browser. From the CLI, `runtime sandbox preview 3000 --public` shares a port ([CLI](/docs/cli)). Related: [coding agent sandbox](/use-cases/coding-agent-sandbox), [per-user dev environments](/use-cases/per-user-dev-environments), [sandbox snapshots](/glossary/sandbox-snapshot), [pause and resume a sandbox](/how-to/pause-and-resume-a-sandbox). Facts on this page were checked on 25 September 2026.