# Live previews

A cloud run's agent can start a server in its sandbox, such as a dev server for the app it is building, and announce it. workbenches.dev then lets members of your organization open it in the browser, while the run works and for a while after it ends.

Previews work in hosted sandboxes only. Runs on a [worker](/docs/workers/setup) have none yet, and neither do Docker runs with the CLI.

## Announce a server

Inside the sandbox the agent runs:

```sh
wbx preview <port> --name <name>
```

`wbx` is a helper the engine puts first on the runner's `PATH` for every run with an outbox. It checks its arguments and that the port is listening, then records the announcement. It never reaches the network.

- `name` matches `^[a-z0-9][a-z0-9-]{0,39}$`.
- `port` is from 1024 to 65535 and not one the engine uses itself. The runner server's port 4096 and Daytona's ports 2280, 22222, and 33333 are reserved.
- A run has at most 8 previews.
- Announcing a name again with another port replaces its preview.

Each accepted announcement emits a `preview.available` event with `name`, `port`, and `protocol` (`http`). On Daytona it carries no `url`, because the address is a signed credential. The run's `previews` list holds the names and ports.

Previews in cloud sandboxes are available to OpenCode, Pi, and Claude Code Workbenches. Announcements come from the runtime independently of the runner's transport.

## Open a preview

On the run's page in the dashboard, each announced preview has an open button. Each click mints a new signed link for that one response. The link is a credential: it is never stored, logged, or put in an event.

Opening a preview requires a signed-in member of the run's organization. API keys and MCP cannot open previews.

## After the run ends

A run that announced a preview and then completed or failed keeps its sandbox running for a preview window instead of deleting it:

- The window lasts 30 minutes from the end of the run.
- Opening a preview during the window extends it to 30 minutes from then.
- It never stays open past 4 hours after the run ended, or past the sandbox time your organization has left.
- A cancelled run gets no window.

While the window is open, the run's `previews_until` is the time it closes. The window's time is billed as sandbox time, at the sandbox's size, when it closes. During the window the runner is stopped and its credential files are removed; servers the agent started keep running with the environment they inherited.

## End the window

The person who started the run, or an owner or admin, can end the window early from the run page. Another member can open previews but not end them. Ending it deletes the sandbox.

## API

| Method | Path                                | Who                                              | Result                                                                                                      |
| ------ | ----------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/runs/:id/previews/:name/links` | Session: member of the run's organization        | 201 `{ "url": "..." }`, a new signed link. 404 for an unknown preview, 409 `The preview is no longer live`. |
| DELETE | `/v1/runs/:id/previews`             | Session: the run's starter, or an owner or admin | 204. 409 `The run has no preview window open`.                                                              |

Both answer `cache-control: no-store`. A run of another organization reads as not found.

## Local runs

On the local runtime, `wbx preview` announces a server on your machine and the CLI prints `Serving <name> at http://127.0.0.1:<port>/`. Nothing keeps the server running after the run ends.