---
title: "Preview a dev server"
description: "Open a dev server that runs in a workspace, in your browser or in the agent's browser, with no public URL."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-opencode.system3inference.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview a dev server

The agent can start a dev server in the workspace, for example on port 3000. You open it on your machine through the Worker. The Worker asks for the workspace password, so the dev server is not public.

## Open a preview

1. Start the dev server in the workspace. It can listen on `127.0.0.1` or on `0.0.0.0`.
2. On your machine, run:

   ```sh
   cf-opencode preview 3000
   ```

The command forwards port 3000 of the workspace to your machine through SSH. It prints `http://localhost:3000` and opens it in your browser. The preview stops when you stop the command with Ctrl-C.

- Nothing is public. No URL exists outside your machine.
- The app is at the root of `localhost`. Asset paths and hot reload work as they do on your machine.
- A paused workspace wakes, as it does for `ssh`.
- Without a workspace name, the command uses the workspace of the current directory. To name one, put it first: `cf-opencode preview my-repo 3000`.
- You can give more than one port: `cf-opencode preview 3000 5173`.
- If the port is in use on your machine, the command uses the next free port and prints it.

| Flag | Effect |
| --- | --- |
| `--no-open` | Do not open the browser. |
| `--web` | Use a URL on the Worker, not a forward. See the next section. |
| `--public` | Make a public URL. See [Public URL](#public-url). |
| `--stop` | Remove a public URL. |
| `--list` | List the public URLs. |

`--web`, `--public`, `--stop`, `--list` and `--json` do not use the forward.

This command needs an `ssh` client on your machine.

## Open a preview on the Worker

Use `--web` on a machine with no `ssh` client, or to open the preview on another device of yours.

1. Make sure that the workspace is awake. Run `cf-opencode connect my-repo` if it is paused.
2. Start the dev server on `0.0.0.0`, not on `127.0.0.1`. For Vite, add `--host 0.0.0.0`.
3. On your machine, run:

   ```sh
   cf-opencode preview my-repo 3000 --web
   ```

The command prints the preview URL, such as `https://cf-opencode.example.workers.dev/preview/my-repo/3000/`. Then it opens the URL in your browser. You do not type a password.

| Flag | Effect |
| --- | --- |
| `--no-open` | Print a sign-in link. Do not open the browser. |
| `--json` | Print one JSON document with `url` and `link`. |

## How the browser signs in

The password is not in the URL. The CLI sends the password in a header and gets a sign-in link from the Worker. The link works one time, for 2 minutes. The browser opens the link, and the Worker gives it a cookie.

The cookie works for one workspace and one port. It stops after 8 hours. To sign in again, run `cf-opencode preview` again.

## Public URL

A public URL needs no password. Use it to show the dev server to another person.

```sh
cf-opencode preview my-repo 3000 --public
```

The command prints a URL such as `https://cf-opencode.example.workers.dev/public/my-repo/<token>/`. Anyone with the URL can open port 3000 of the workspace while the workspace is awake.

| Command | Effect |
| --- | --- |
| `cf-opencode preview my-repo --list` | List the public URLs of the workspace. |
| `cf-opencode preview my-repo 3000 --stop` | Remove the public URL of port 3000. |
| `cf-opencode preview my-repo --stop` | Remove all public URLs of the workspace. |

There is no public URL until you run `--public`. These commands need the control token. The agent in the workspace does not have the control token, so it cannot make a public URL.

## From inside the workspace

The agent runs:

```sh
cf-opencode-preview 3000
```

The command prints the preview URL for you. It also checks that a server listens on port 3000 on `0.0.0.0`. If no server listens, it prints a `Failed:` line with the fix.

## The agent's own browser

The remote browser of the workspace opens the dev server at `http://p3000.preview.internal/`. This address works only in that browser. It is not on the Internet.

```sh
cf-opencode-fetch http://p3000.preview.internal/
cf-opencode-fetch --screenshot home.png http://p3000.preview.internal/
cf-opencode-browse --preview 3000
```

`cf-opencode-fetch http://localhost:3000/` does the same as the first command. A browser session from `cf-opencode-browse --preview` can open up to 4 ports. Browser Run sends the requests for these addresses to the Worker, and the Worker sends them to the port. These addresses use HTTP only. Hot reload does not connect there.

## Limits

- A `--web` preview does not wake a paused workspace. The forward does. A dev server stops when the workspace pauses. Run `cf-opencode connect`, then start the dev server again.
- A request through a preview counts as use. An open preview that loads pages keeps the workspace awake.
- The preview is under the path `/preview/<workspace>/<port>/`. A page that loads an absolute path, such as `/assets/app.js`, asks for a path outside the preview. The Worker sends most of these requests back to the preview. Hot reload can fail to connect. Reload the page by hand, or set the base path of the dev server. For Vite, add `--base /preview/<workspace>/<port>/`.
- All previews use the same origin as the Worker. A page in one preview can read another preview that the same browser is signed in to. It can also call `/oc` if the browser has a workspace password cached, which happens only when you type one into a browser prompt. It cannot open `/shell`, `/ssh` or `/browse`. Do not open code that you do not trust in that browser profile. See [Security and trust](https://cf-opencode.system3inference.dev/docs/concepts/security/#previews).

## Errors

| Error | Fix |
| --- | --- |
| `<workspace> is paused, and a dev server does not survive a pause` | Run `cf-opencode connect <workspace>`, start the dev server, then run `cf-opencode preview` again. |
| `"<x>" is not a port from 1024 to 65535` | Give the port of the dev server. |
| `no free port near <port> on this machine` | Close what uses the ports near it, then retry. |
| `nothing answers on port <port> in <workspace>` | Start the dev server on `0.0.0.0`. |
| `--public, --stop and --list do not go together` | Pass one of them. |
| `<n> public previews already exist` | Remove one with `cf-opencode preview <workspace> <port> --stop`. |
| `port <port> listens on 127.0.0.1 only` | Start the dev server with `--host 0.0.0.0`. |
| `the sign-in link was used or is older than 2 minutes` | Run `cf-opencode preview <workspace> <port>` again. |
| `bad port` | Use the port of the dev server, from 1024 to 65535. Port 4096 is OpenCode. |
| `this Worker has no preview route` | Run `cf-opencode upgrade`. |

Source: https://cf-opencode.system3inference.dev/docs/guides/preview/index.mdx
