# Port preview Open a web server you started inside a workspace at a URL in your browser. > [!NOTE] > Previews are switched on per workspace **Type**. If your workspace's **…** menu has no **Ports…** entry, its type doesn't have previews turned on yet. Ask your account team. A preview gives a web server running in your workspace its own URL, so you can open it in your browser. There's no SSH tunnel to set up and nothing to forward from your own machine. Start a server in a workspace terminal, for example: ```sh streamlit run app.py ``` Then open port 8501 from **Ports…**. ## Where it lives **Ports…** is in the **…** menu at the end of the workspace's row on the **Workspaces** page, beside **Files…**. It lists every port listening inside the workspace, with the process holding each one. The list refreshes every few seconds while it's open, so you can leave it up and start your server afterwards. Each row has an **Open** button and a button that copies the link. Both give you a URL of this shape: ``` https://ws.privatemind.com/w//-/preview// ``` Previews open on `ws.privatemind.com`, the address every workspace page uses. It is kept apart from privatemind.com so that code running in a workspace can't act as you in the PrivateMind app. You never type the link yourself, though a couple of servers need it (see below). It stays the same for the life of the workspace, restarts included, so you can keep it in a script. ## Who can open it A preview link has the same access check as every other workspace surface and follows the workspace's visibility. While a workspace is private, only you and your org's compute admins can open its previews. Make it **shared** and anyone in your org can, as with JupyterLab or the terminal. It is never a public link. Someone outside your org, or someone who isn't signed in, is refused. See [Sharing with your team](https://docs.privatemind.com/workspaces.html#sharing-with-your-team). To show one server to people who can't open the workspace, publish it with [App Central](https://docs.privatemind.com/app-central.html). They get that port and nothing else in the workspace, and it still isn't a public link. ## Knowing who is using it Every request your server gets through a preview says who sent it, in these headers: | Header | What it holds | | --- | --- | | `X-Auth-User-Id` | The person's PrivateMind user id, a number. It never changes, so key anything you store per person on it. | | `X-Auth-Email` | Their email address. | | `X-Auth-Name` | Their name, for display only. Accents are dropped, and a name that can't be written in plain ASCII becomes the start of their email address. | | `X-Auth-Role` | Their role in your organisation, such as `user` or `org_admin`. | PrivateMind sets these after checking the person's sign-in, on every request, including the one that opens a websocket. Any `X-Auth-` header the browser sends is removed first, and so is any header whose name has a character other than a letter, a digit or a dash, so a lookalike such as `X_Auth_User_Id` never reaches your server. In FastAPI, for example: ```python from fastapi import FastAPI, Request app = FastAPI() @app.get("/whoami") def whoami(request: Request): return { "id": request.headers.get("x-auth-user-id"), "name": request.headers.get("x-auth-name"), } ``` People who open your server as a published App Central app, and can't open the workspace itself, get none of these headers: a published app isn't told who is viewing it. A request with no `X-Auth-User-Id` comes from one of those viewers. If your server keeps state per person, decide what those requests get, such as a read-only view, or every viewer shares one copy and they overwrite each other. Your server isn't told the visitor's IP address. `X-Real-Ip` and the other forwarding headers it sees describe PrivateMind's own network. If your server sets cookies, set their `Path` to its preview prefix (see [Servers that build their own URLs](https://docs.privatemind.com/port-preview.html#servers-that-build-their-own-urls)). Every workspace shares `ws.privatemind.com`, so a cookie set on `/` is also sent to any other workspace's server the same browser opens. ## Most servers need nothing Requests arrive at your server with the `/w//-/preview/` prefix removed, so it sees the paths it expects: `/`, `/static/app.css`. Its host is `ws.privatemind.com` and its scheme `https`, as if the browser had called it directly. Any server whose pages link with relative URLs works with nothing configured. Streamlit and `python -m http.server` both do. Your server can bind any address: localhost is fine, and so is every interface. Websockets pass through, so streaming responses work and Streamlit's own socket connects without help. To see it working: ```sh cd ~/projects/my-app python -m http.server 8000 ``` Open the **…** menu, then **Ports…**, find 8000 and click **Open**. ## Servers that build their own URLs Many frameworks write links that start at the root of the domain: `/static/app.css`, FastAPI's `/openapi.json`, Gradio's `/gradio_api/...`, Dash's `/_dash-component-suites/...`. Those requests never reach your server, so the page loads without styling or stops responding. Each framework has a setting for being served under a path. It changes the URLs the server *builds* and leaves the paths it *accepts* alone. The value is your preview prefix, a path with no host: `/w//-/preview/`. Every tab of the workspace shows the first part. A terminal open at `https://ws.privatemind.com/w/acme/python-slim-cpu-a1b2c-9e3f…/terminal/` means the prefix for port 8000 is `/w/acme/python-slim-cpu-a1b2c-9e3f…/preview/8000`. | Server | Setting | | --- | --- | | **FastAPI / uvicorn** | `uvicorn main:app --port 8000 --root-path /w//-/preview/8000` | | **Gradio** | `demo.launch(server_port=7860, root_path="/w//-/preview/7860")` | | **Dash** | `Dash(__name__, requests_pathname_prefix="/w//-/preview/8050/")`, with the trailing slash | | **Flask** | `ProxyFix`, below. It needs no path. | Leave Streamlit's `server.baseUrlPath` unset. With it set, every page of the app is a 404. The prefix also arrives on every request in the `X-Forwarded-Prefix` header. A server that reads it from there needs no path at all, and keeps working if you move it to another workspace. Flask does this with Werkzeug's `ProxyFix`: ```python from werkzeug.middleware.proxy_fix import ProxyFix app.wsgi_app = ProxyFix(app.wsgi_app, x_for=0, x_proto=1, x_host=1, x_prefix=1) ``` FastAPI can do the same with a small middleware in place of `--root-path`. It has to set `path` as well as `root_path`, or static files return 404: ```python class PrefixFromHeader: def __init__(self, app): self.app = app async def __call__(self, scope, receive, send): if scope["type"] in ("http", "websocket"): headers = dict(scope["headers"]) prefix = headers.get(b"x-forwarded-prefix", b"").decode("latin-1").rstrip("/") if prefix: scope = dict(scope, root_path=prefix, path=prefix + scope["path"]) await self.app(scope, receive, send) app.add_middleware(PrefixFromHeader) ``` ## Vite and Next dev servers The Vite and Next dev servers don't work behind a preview, and no setting fixes it. Both write their asset URLs from the root (`/@vite/client`, `/src/main.js`), so those requests never reach your server. Setting their `base` option makes the dev server redirect to that base, the redirect comes back through the proxy, and the browser loops. Building the app and serving the output does work, if the build uses relative asset paths. By default Vite writes them from the root (`/assets/…`), which a preview never receives, so the page comes up blank. Pass `--base ./`: ```sh npm run build -- --base ./ python -m http.server 8000 -d dist ``` Next's production server, `next start`, hasn't been tested behind a preview. ## Which ports you can use Ports 1024 to 65535, minus the ones the workspace's own surfaces hold: 2222, 7681 to 7685, 7691, 7692, 7694, 8443, 8444 and 8888. Those never appear in the **Ports…** list, and opening one directly is refused with a page naming the surface that holds it. 8888 is the one people hit most, because it's JupyterLab's port here and the default for many other tools. The usual defaults are free: 8000 for uvicorn and `python -m http.server`, 8501 for Streamlit, 7860 for Gradio. ## Redirects When your server redirects the browser to one of its own paths, you stay inside the preview. `Location: /login` means "this port's `/login`", so the preview adds the prefix back. Relative redirects, and redirects that already carry the prefix, are left alone. So is a redirect to another host, which takes you there. ## Troubleshooting **"Nothing is listening on port 8000."** A short page with this message means the request reached the workspace but found no server on the port. Usually the process exited, or it's on another port. Read the port off its startup line in its terminal, and reopen **Ports…** to see what's listening now. **Your port isn't in the list.** Ports below 1024 and the [ports the workspace holds](https://docs.privatemind.com/port-preview.html#which-ports-you-can-use), such as 8888, don't show and can't be previewed. Move the server to another port. If it's already on a free port, check that it started. **The page loads with no styling.** The HTML came through but the CSS and JavaScript didn't, because the page asks for them from the root of the domain. Set the server's [root-path option](https://docs.privatemind.com/port-preview.html#servers-that-build-their-own-urls) and start it again. For a Vite or Next dev server, build the app with relative asset paths and serve the output. **A link took you somewhere unexpected.** If you land on the workspace list or a sign-in page, your server sent the browser to an absolute URL on another host, and previews pass those through unchanged. ## Where next - [Workspaces](https://docs.privatemind.com/workspaces.html): the environment itself, its surfaces, sharing, and SSH access from your own machine. - [App Central](https://docs.privatemind.com/app-central.html): publish one port to the people you choose, without giving them the workspace. - [Deploy a model](https://docs.privatemind.com/model-deployments.html): for a long-lived endpoint on the API, not a quick look at something you're building.