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:

TypeScriptimport { Sandbox } from "withruntime";const sbx = await Sandbox.create({ idlePauseSeconds: 900, labels: { project: "p-123" } });await sbx.files.write(  "/workspace/app/index.html",  "<!doctype html><h1>Built by the agent</h1>", // 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

Pythonfrom withruntime import Sandboxsbx = Sandbox.create(idle_pause_seconds=900, labels={"project": "p-123"})sbx.files.write("/workspace/app/index.html", "<!doctype html><h1>Built by the agent</h1>")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).

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:

TypeScriptimport { 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);

Pythonfrom withruntime import Runtimeruntime = 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:

TypeScriptimport { 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)
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:

TextCPU:     200 × 3 h × 0.1 vCPU × $0.025            = $1.50Memory:  200 × 3 h × 4 GiB × $0.0075              = $18.00Paused:  200 × 1 GB × $0.08 × 717 h / 720 h       = $15.93Total:                                              $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). The snapshot is storage at the same $0.08 rate. New accounts get 50 free sandbox hours, no card.

Start

Terminalnpx withruntime sandbox run --trial --keep -- python3 --version

The first run prints a link to approve in your browser. From the CLI, runtime sandbox preview <id> 3000 --public shares a port (CLI).

Facts on this page were checked on 25 September 2026.