Core Concepts

The Container

Laboratory OS runs in a single Docker container.

You own the container and run it on your own compute.

The Laboratory OS container has many responsibilities:

• Establish and maintain secure tunnel connections.
• Manage subdomains for each installed app.
• Serve system utilities such as the file browser, terminal, and VS Code.
• Provide seamless one-click installations of any software in the App Library.
• Serve the web desktop UI behind strong authentication/authorization gates.

State

The container persists state in a mounted volume (/workspace). Your installed apps, downloaded models, desktop settings, and configuration all live there. Stopping and restarting the container leaves everything intact.

See persistence for more details.

Tunnels

Laboratory OS uses an outbound tunnel to make your instance accessible to authenticated clients. No inbound ports, no firewall rules, no reverse proxy.

When the container starts, it connects outward through Uplink, joins a Tailscale tailnet, or does both. Uplink can use the managed edges assigned to an account or a self-hosted key-mode edge. Laboratory OS is designed to be aggressively portable; the same container setup works whether you run it on a laptop, home server, or cloud VM.

App Routes

Every app you install gets its own route. With Uplink, that route is a dedicated host derived from the Laboratory identity and route name:

https://{route}-{laboratory-id}.{edge-domain}

For example, if your slug is abcde and you’re running ComfyUI and Open WebUI:

https://comfyui-example.uplink.computer
https://openwebui-example.uplink.computer

With Tailscale, wildcard subdomains are unavailable, so apps use dedicated HTTPS ports on the lab’s tailnet name instead. Routes are reconciled automatically as apps start and stop. Uplink routes can also be protected with route-scoped sharing tokens; Tailscale routes follow the tailnet’s ACLs.

Security Model

Access is split by surface:

• in device-token mode, the managed edge authenticates visitors against the owning Uplink account before requests reach the container.
• in self-hosted-edge mode, the lab access token printed during boot gates the root route.
• in Tailscale mode, access follows the tailnet’s ACLs.
• privileged base-host routes like VS Code, terminals, and filebrowser are restricted by the selected edge’s access policy.
• protected published app routes use separate route-scoped external access tokens that can be independently generated, shared, and revoked.

See the full Security Architecture page for a deeper user-facing explanation of what is protected, how sharing works, and what the current limits are.

Remote-Access Methods

Laboratory OS supports three remote-access methods:

• Uplink account: pass UPLINK_DEVICE_TOKEN. Create the token in the Uplink console. It is host-bound, serve-only, and selects the account that owns the device and tunnels.
• Self-hosted edge: pass UPLINK_EDGE and UPLINK_EDGE_API_KEY. The Laboratory instance connects directly to that key-mode edge without an account login. The lab access token printed during boot protects its root route.
• Tailscale: pass TS_AUTHKEY to join the station to a tailnet. Access follows the tailnet’s ACLs; TS_HOSTNAME optionally chooses the device hostname.

Tailscale can run on its own or alongside either Uplink mode. In account mode, the instance appears as a Device and its routes appear as Tunnels in Uplink. There is no separate Laboratory dashboard.