Quick Start

Laboratory OS supports three remote-access methods: managed Uplink, a self-hosted Uplink edge, and Tailscale. Tailscale can run alone or alongside either Uplink mode.

Step 1: Choose an Access Method

Uplink account (managed edges)

Open Device Tokens in the Uplink console and create a token for this Laboratory host. Copy the updv_… secret when it is shown; it cannot be displayed again and binds to the first host that uses it.

export UPLINK_DEVICE_TOKEN='updv_...'

Self-hosted Uplink edge

Use the domain and static API key from your own key-mode edge:

export UPLINK_EDGE='edge.example.com'
export UPLINK_EDGE_API_KEY='uek_...'

UPLINK_EDGE_ADDRESS is optional when the tunnel dial address differs from the public edge domain.

Tailscale

Create an auth key for the tailnet the station should join:

export TS_AUTHKEY='tskey-auth-...'

You can use this by itself or add it to either Uplink configuration.

Step 2: Start the Container

For account mode:

docker run -d --restart unless-stopped \
  --gpus all \
  --pid host \
  --name laboratory \
  -e UPLINK_DEVICE_TOKEN="$UPLINK_DEVICE_TOKEN" \
  -v laboratory_os_workspace:/workspace \
  openlaboratoryorg/laboratory-os

For a self-hosted edge, replace the token line with:

  -e UPLINK_EDGE="$UPLINK_EDGE" \
  -e UPLINK_EDGE_API_KEY="$UPLINK_EDGE_API_KEY" \

For Tailscale, replace the token line with -e TS_AUTHKEY="$TS_AUTHKEY". To use Tailscale alongside Uplink, add that line without removing the Uplink variables.

No GPU? Drop --gpus all to run CPU-only. GPU acceleration is strongly recommended for image generation and LLMs.

NVIDIA GPU on Linux? Make sure NVIDIA Container Toolkit is installed on your host first.

The container starts Uplink and prints the assigned Laboratory URL after the tunnel connects. In device-token mode it also appears in the account’s Uplink Devices and Tunnels pages.

Step 3: Open Your Desktop

Read the assigned URL from the logs:

docker logs -f laboratory

Open the reported URL directly. Managed Uplink uses account SSO. A self-hosted edge asks for the lab access token printed during boot. Tailscale access follows your tailnet ACLs.

Step 4: Install an App

From the desktop, open the Apps panel and pick an app — for example, ComfyUI. Click Install. The app downloads, installs, and starts automatically.

Once running, it gets its own route. Uplink uses a dedicated host; Tailscale uses a dedicated HTTPS port on the lab’s tailnet name. A desktop shortcut opens it.

Step 5: Download a Model

Open the Model Library panel from the desktop. Browse the library and click Download on any model. It downloads directly into the container’s shared model directory, and becomes immediately available to all compatible apps.

What’s Next

Core Concepts — How routes, tunnels, and auth work