On Runtime, a preview gives one port of a sandbox an HTTPS address. The
address is private by default. A visit wakes a paused sandbox, so an idle
preview costs storage rather than compute. Addresses live under
runtimehost.com. That domain is separate from Runtime's own site. What a
sandbox serves never shares an origin with your account
(security).
Why it matters for AI agents
An agent that builds a web app has to show it to someone. A screenshot does not show whether the buttons work. A link lets the user click through the real app. The same link lets the agent test its own work with a browser. It also lets a reviewer check a pull request without cloning it. The address must be safe to send around. It should expose one port, not the whole machine, and you must be able to revoke it.
Runtime previews
| Property | Detail |
|---|---|
| What it exposes | One port of one sandbox, over HTTPS; WebSockets work |
| Default access | Private: the x-runtime-preview-token header, or the urlWithToken link, which carries it |
| Public | visibility: "public" for an address anyone can open, on a paid sandbox |
| Revoke | previews.rotate(port) refuses every token issued so far |
| Stop sharing | previews.delete(port) |
| Domain | runtimehost.com, never withruntime.com |
| Paused sandbox | A visit wakes it behind a short "Waking up" page that reloads itself |
| Your own domain | Paid accounts can point a verified custom domain at a sandbox port |
Share a port
Start the server with spawn, not exec, so it keeps running after the call
returns:
TypeScriptimport { Sandbox } from "withruntime";const sbx = await Sandbox.create({ idlePauseSeconds: 900 });await sbx.spawn("python3 -m http.server 8000");const preview = await sbx.previews.create(8000);console.log(preview.urlWithToken); // send this link to the reviewerawait sbx.previews.rotate(8000); // the old link stops workingPythonfrom withruntime import Sandboxsbx = Sandbox.create(idle_pause_seconds=900)sbx.spawn("python3 -m http.server 8000")preview = sbx.previews.create(8000)print(preview["urlWithToken"])Terminalruntime sandboxes preview "${id}" 8000 --publicWith idlePauseSeconds, the sandbox pauses when visits stop. The server stays
in memory during the pause. The next visit to the same link wakes the sandbox.
Preview URL or port forwarding?
A preview is for other people and for browsers you do not control. For your own
machine, use runtime sandboxes port-forward. It reaches any port on the
sandbox through the API with your key. It shares nothing with anyone else
(SSH and editors).
Related
- How to preview apps an AI agent builds
- What is an ephemeral environment?
- What is idle pause?
- Share a port in the JavaScript SDK
- Networking
Facts on this page were checked on 25 October 2026.