# 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](/docs/security#network-access)).

## 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:

```ts check
import { 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 reviewer
await sbx.previews.rotate(8000); // the old link stops working
```

```python check
from withruntime import Sandbox

sbx = Sandbox.create(idle_pause_seconds=900)
sbx.spawn("python3 -m http.server 8000")
preview = sbx.previews.create(8000)
print(preview["urlWithToken"])
```

```bash no-run
runtime sandbox preview "${id}" 8000 --public
```

With `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](/docs/editors)).

## Related

- [How to preview apps an AI agent builds](/use-cases/preview-agent-built-apps)
- [What is an ephemeral environment?](/glossary/ephemeral-environment)
- [What is idle pause?](/glossary/idle-pause)
- [Share a port in the JavaScript SDK](/docs/javascript#share-a-port)
- [Networking](/docs/networking)

Facts on this page were checked on 25 September 2026.