Run Laboratory OS

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

Basic Usage

docker run --gpus all \
  -e UPLINK_API_KEY='your-account-key' \
  openlaboratoryorg/laboratory-os

The container starts, establishes a tunnel, and logs your assigned URL within the first 30 seconds. Open app.laboratory.computer to access your desktop.

Options Reference

Flag	Description
`--gpus all`	Pass through all NVIDIA GPUs. Requires NVIDIA Container Toolkit.
`-e UPLINK_API_KEY=...`	Required. Your account key from openlaboratory.com. The lab serves on your `*.laboratory.computer` URL.
`-v /host/path:/workspace`	Bind mount for persistent storage. All app data and models are written to `/workspace`.
`-v lab-workspace:/workspace`	Named Docker volume for persistence — simpler than a bind mount.
`-d`	Run detached (in the background).
`--restart unless-stopped`	Auto-restart on failure or host reboot.
`--name laboratory`	Assign a name for easy `docker stop laboratory` / `docker start laboratory`.
`--pid host`	Share the host PID namespace — required for process monitoring inside the container.

Choosing an Image

Tag	Architecture	Base	Use when
`:latest`	amd64 + arm64	Ubuntu 22.04	Default for most setups. Docker pulls the matching CPU image for your host.
`:amd64`	amd64	Ubuntu 22.04	Pin x86_64 hosts explicitly. GPU passthrough works via NVIDIA Container Toolkit.
`:arm64`	arm64	Ubuntu 22.04	Pin ARM hosts explicitly — Apple Silicon VMs, Raspberry Pi, etc.
`:cuda-12.8` / `:cuda-12` / `:cuda`	amd64	CUDA 12.8 + Ubuntu 22.04	Apps that compile CUDA extensions at install time.
`:cuda-13.2` / `:cuda-13`	amd64	CUDA 13.2 + Ubuntu 22.04	Apps requiring the latest CUDA toolkit.

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_API_KEY='your-account-key' \
  -v lab-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
    environment:
      - UPLINK_API_KEY=your-account-key
    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, replace - lab-workspace:/workspace with - /your/host/path:/workspace and remove the volumes: block at the bottom.

Advanced: Self-Hosted Edge

The primary path above is managed — one UPLINK_API_KEY and your lab serves on a *.laboratory.computer URL, with the edge handling sign-in. If you’d rather run your own edge (no Open Laboratory account, password auth, fully self-hosted), set UPLINK_EDGE and UPLINK_EDGE_API_KEY for your edge instead of UPLINK_API_KEY:

docker run --gpus all \
  -e UPLINK_EDGE='your-edge-domain' \
  -e UPLINK_EDGE_API_KEY='your-edge-key' \
  -v lab-workspace:/workspace \
  openlaboratoryorg/laboratory-os

In this mode the lab is independent of Open Laboratory: it won’t appear in the dashboard and account env-vars are unavailable, since there is no managed account.

CPU-Only Mode

Drop --gpus all to run without a GPU:

docker run \
  -e UPLINK_API_KEY='your-account-key' \
  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 like OpenCode or Claude Code against external LLM APIs. The container safely isolates agent permissions from your host.
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 account key, tunnel, and desktop work 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 will not boot on CPU, they require GPU detection at startup. LLM inference via Ollama and llama.cpp works but is significantly slower without a GPU.