Workspace gateway & reverse proxies

LabPod deliberately separates the platform UI and API from workspace applications. This prevents JavaScript supplied by a notebook, extension, or container image from calling the platform API with the browser’s LabPod session.

The paired ports

With the default LABPOD_PORT=24680 configuration:

Browser origin	Port	Serves
Platform	24680	Sign-in, the LabPod UI, and /api/*
Workspace gateway	24681	Only /ws/<workspace-id>/... application traffic

Researchers start at the platform address, for example https://labpod.example:24680. When they open JupyterLab, Code, RStudio, or an app they declared themselves, LabPod redirects the browser to the workspace-gateway origin. The gateway rejects the platform UI, sign-in, and API paths.

Allow both ports through the LAN firewall or VPN. If the gateway’s adjacent port is blocked, occupied, or sent to the platform listener, workspace applications cannot open even though the LabPod dashboard still loads.

Reverse-proxy rule

A reverse proxy needs two browser-visible origins. They may use two hostnames, two external ports, or both. Do not route /api/* and /ws/* through one public hostname-and-port pair.

For example, a proxy can keep the default port pair visible to the browser:

https://labpod.example:24680  ->  http://127.0.0.1:24680  # platform UI and API
https://labpod.example:24681  ->  http://127.0.0.1:24681  # workspace gateway only

Or it can use separate public hostnames. In either case, forward WebSocket upgrades on both origins and preserve the original Host and HTTPS scheme headers only from that trusted proxy. Set LABPOD_TRUST_PROXY_HEADERS=true only when direct client access to the LabPod listeners is blocked.

Do not configure a catch-all proxy rule that sends the workspace hostname to the platform port, or sends the platform hostname’s /ws/ path back to the same origin. The platform redirects workspace paths precisely to keep the origins separate.

SSH and LabPod Connect

For remote access, expose only SSH publicly. LabPod Connect forwards the configured platform port and its adjacent workspace-gateway port as a pair. On the computer running LabPod Connect, both local ports must be free. Direct HTTP and HTTPS connections use the same paired-origin model inside the workstation pane.

Troubleshooting

If an app’s Start action succeeds but Open fails:

1. Confirm that both platform and gateway ports are reachable from the browser or desktop client.
2. Check that the proxy forwards WebSocket upgrades and retains the two origins.
3. Read the application’s workspace card. A readiness error includes the address and HTTP status under Show technical details. A wrong launcher path prefix does not recover by retrying; correct the launcher configuration or follow the template’s guidance.

For the host-side loopback protection that keeps local users from bypassing the authenticated gateway, see Security & hardening.