What is a preview URL?
A preview URL is a temporary web address for an app running in a development or test environment, so people can open it before it ships.
On Runtime a preview gives one port of a sandbox an HTTPS address that is
private by default, and a visit wakes a paused sandbox, so an idle preview
costs storage rather than compute. Addresses live under runtimehost.com,
a domain kept apart from Runtime's own site, so 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 hides whether the buttons work; a link lets the user click through the real thing. The same link lets the agent test its own work with a browser, or lets a reviewer check a pull request without cloning it. The address has to be safe to send around: it should expose one port, not the machine, and be revocable.
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 a one-time urlWithToken link |
| Public | visibility: "public" for an address anyone can open |
| 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 proved 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 sandbox preview "${id}" 8000 --publicWith idlePauseSeconds, the sandbox pauses with the server still in memory
when visits stop, and the next visit to the same link resumes it, usually in
about half a second.
Preview URL or port forwarding?
A preview is for other people and for browsers you do not control. For your own
machine, runtime sandbox port-forward reaches any port on the sandbox through
the API with your key, and shares nothing (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 September 2026.