Run Laboratory OS

Laboratory OS runs as a Docker container. See Install Dependencies for setup instructions.

Basic Usage

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

The example uses an Uplink account device token. Create one in the Uplink console, then start the container. It establishes the tunnel and logs the assigned desktop URL.

Options Reference

Choosing an Image

The :latest image is the right choice for most setups and now resolves to either the amd64 or arm64 CPU image automatically. The CUDA-bundled tags remain amd64-only, are larger, and are required for some apps that build native extensions (e.g. bitsandbytes, flash-attention) during installation. If an app install fails with a CUDA compile error, switch to a CUDA image.

For example, pass a tag to run a CUDA-bundled image. Everything else stays the same:

docker run -d --restart unless-stopped \
  --gpus all \
  --pid host \
  --name laboratory \
  -e UPLINK_DEVICE_TOKEN='your-device-token' \
  -v laboratory_os_workspace:/workspace \
  openlaboratoryorg/laboratory-os:cuda-12.8

Docker Compose

A sample docker-compose.yml for a persistent GPU setup:

services:
  ol:
    image: openlaboratoryorg/laboratory-os:latest
    restart: unless-stopped
    pid: host
    environment:
      - UPLINK_DEVICE_TOKEN=your-device-token
    volumes:
      - type: volume
        source: laboratory_os_workspace
        target: /workspace
    gpus: all # Remove for non-GPU mode

volumes:
  laboratory_os_workspace:

Run it:

docker compose up -d

To use a CUDA image, change the image: line to openlaboratoryorg/laboratory-os:cuda-12.8 (or whichever tag you need).

To use a bind mount instead of a named volume, change the service’s volume entry to - /your/host/path:/workspace and remove the top-level volumes: block.

To use a custom Uplink edge instead, replace UPLINK_DEVICE_TOKEN with UPLINK_EDGE=your-edge-domain and UPLINK_EDGE_API_KEY=your-edge-key.

To join a tailnet, add TS_AUTHKEY=your-tailscale-auth-key. This works by itself or alongside either Uplink configuration.

Self-Hosted Uplink Edge

The other supported path is a custom key-mode Uplink edge. Set UPLINK_EDGE and UPLINK_EDGE_API_KEY together instead of UPLINK_DEVICE_TOKEN:

docker run -d --restart unless-stopped \
  --gpus all \
  --pid host \
  --name laboratory \
  -e UPLINK_EDGE='your-edge-domain' \
  -e UPLINK_EDGE_API_KEY='your-edge-key' \
  -v laboratory_os_workspace:/workspace \
  openlaboratoryorg/laboratory-os

In this mode the lab does not log into an Uplink account or appear in an account’s Devices list. The lab root is protected by the access token printed during boot.

Tailscale

Pass a Tailscale auth key to join the station to your tailnet. It can be the only remote-access method or run alongside either Uplink mode:

docker run -d --restart unless-stopped \
  --gpus all \
  --pid host \
  --name laboratory \
  -e TS_AUTHKEY='your-tailscale-auth-key' \
  -v laboratory_os_workspace:/workspace \
  openlaboratoryorg/laboratory-os

Tailscale access follows your tailnet ACLs. Set TS_HOSTNAME if you want to choose the station’s tailnet hostname.

CPU-Only Mode

Drop --gpus all to run without a GPU:

docker run -d --restart unless-stopped \
  --pid host \
  --name laboratory \
  -e UPLINK_DEVICE_TOKEN='your-device-token' \
  -v laboratory_os_workspace:/workspace \
  openlaboratoryorg/laboratory-os

The desktop, tunnel, and app management all work identically — the difference is purely in AI inference performance. CPU-only mode is useful for:

• Coding agent environments — Run coding agents against external LLM APIs while keeping their default files and tools inside the container. Treat the container as a convenience boundary, not a sandbox for hostile code.
• Cloud dev environments — Run VS Code and a terminal from any remote server, no GPU required.
• Jupyter notebooks — Data science, scripting, anything not GPU-bound.
• Testing your setup — Verify your Uplink credentials, tunnel, and desktop before moving to a GPU host.
• Small LLMs — Llama 3.2 3B or Phi-3 Mini run at usable speeds on CPU (16+ core machines recommended).

Note: Most image-generation apps require a GPU. LLM inference via Ollama and llama.cpp works on a CPU but is significantly slower.