Get API key

Port preview

View as Markdown

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:

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

Text
https://ws.privatemind.com/w/<org>/<workspace>-<nonce>/preview/<port>/

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.

To show one server to people who can't open the workspace, publish it with App Central. 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). 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/<org>/<workspace>-<nonce>/preview/<port> 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:

shell
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/<org>/<workspace>-<nonce>/preview/<port>. 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/<org>/<workspace>-<nonce>/preview/8000
Gradio demo.launch(server_port=7860, root_path="/w/<org>/<workspace>-<nonce>/preview/7860")
Dash Dash(__name__, requests_pathname_prefix="/w/<org>/<workspace>-<nonce>/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 ./:

shell
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, 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 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: the environment itself, its surfaces, sharing, and SSH access from your own machine.
  • App Central: publish one port to the people you choose, without giving them the workspace.
  • Deploy a model: for a long-lived endpoint on the API, not a quick look at something you're building.