Skip to content
LabPod LabPod LabPod Docs

Desktop app

LabPod Connect is a lightweight native launcher, not a separate interface. It loads the same LabPod web app you’d reach in a browser, but wraps it in a native window so you don’t have to remember http://<ip>:<port> URLs.

What it does

Section titled “What it does”
  • Saved servers - register each LabPod workstation you access (a label and a URL). The list persists across launches.
  • One-click connect - click a server in the left sidebar to load it in the main pane.
  • Test - the app tests reachability before connecting.

Everything else - logging in, creating workspaces, opening Jupyter, using the terminal - is the same web UI running inside the pane. Workspace applications stay in that workstation pane.

Platforms

Section titled “Platforms”

The app uses the system’s built-in web renderer (WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux). Binaries are unsigned at this time.

LabPod Connect is versioned and released independently from the LabPod server. Download the latest desktop bundles from the LabPod Connect releases page.

Adding a server

Section titled “Adding a server”
  1. Click + (or Add) in the sidebar.
  2. Enter a label and the workstation IP or hostname under Host. Keep Port at 24680 unless your operator configured another LabPod port. You can also paste a complete URL such as http://192.168.1.10:24680 into Host.
  3. Click Test to verify the server is reachable.
  4. Click Save.

Click the server name to load it. The LabPod web app opens in the main pane - log in as normal.

If Test cannot reach a server

Section titled “If Test cannot reach a server”
  1. Open http://<host>:<port>/api/version in a browser on the same computer. A LabPod server returns JSON containing a non-empty version value.
  2. Confirm the Port field still contains the operator’s LabPod port (24680 by default). A blank port means standard HTTP port 80 or HTTPS port 443.
  3. On macOS 15 or later, open System Settings → Privacy & Security → Local Network and enable LabPod Connect, then retry. Grant the prompt when a newly installed version first contacts a LAN workstation.
  4. Diagnose the installed /Applications/LabPod Connect.app, not a separate local development build. macOS can track local builds and downloaded unsigned copies as different network-permission identities. Avoid keeping multiple copies open while checking the permission.

Test shows the complete native connection error. On Windows and Linux there is no equivalent per-app LAN permission; check the address, routing or VPN, firewall, and server listener instead.

Remote access

Section titled “Remote access”

The app supports two ways to reach a server that isn’t on your local network:

SSH tunnel

Section titled “SSH tunnel”

If you can SSH to the workstation, the app can open a tunnel for you:

  1. Add the server with an http://127.0.0.1:<localport> URL.
  2. Configure the SSH connection details: hostname, port, SSH username.
  3. Click Connect in the sidebar. The app opens an SSH session and forwards the local platform port and its adjacent workspace-gateway port to the workstation. Both local ports must be free.
  4. Your SSH host key is verified using trust-on-first-use (TOFU) and stored in your ~/.ssh/known_hosts. A changed key blocks the connection until you explicitly re-verify it.

Your private key is generated locally per machine and never leaves your device. The key is authorized to the server once using your LabPod password (which is then discarded). An optional passphrase protects the key and is stored in the OS keyring.

Self-signed TLS

Section titled “Self-signed TLS”

If your server is configured with a self-signed HTTPS certificate:

  1. Use an https:// URL when adding the server.
  2. The app pins the certificate’s SHA-256 fingerprint on first connection (trust-on-first-use).
  3. Subsequent connections verify the fingerprint matches. If it changes (e.g. the certificate was renewed), the app warns you and you must re-pin explicitly.
  4. To get the fingerprint your admin configured: sudo labpod admin tls-fingerprint.

If you clear a saved HTTPS pin on Linux, restart LabPod Connect before you contact that server again. WebKit keeps a previous certificate exception until the application exits; the restart makes the next connection verify and pin the certificate it receives.

Connection data

Section titled “Connection data”

The server list is stored locally on your machine at:

PlatformPath
Windows%APPDATA%\com.labpod.connect\connections.json
macOS~/Library/Application Support/com.labpod.connect/connections.json
Linux~/.config/com.labpod.connect/connections.json