Install & first boot

This walks an operator from a bare Linux GPU workstation to a running LabPod server with a root admin account. Plan on 10–15 minutes, plus image-pull time the first time a user creates a workspace.

Before you start, skim Requirements. The installer’s --check mode verifies most of them for you.

What you need

• A supported Linux host: Ubuntu/Debian (apt) or Fedora/RHEL/Rocky (dnf).
• sudo / root on that host.
• Network access to the distro package repos and the NVIDIA container-toolkit repo (the installer adds Podman and the GPU toolkit for you).
• For GPU workspaces: an NVIDIA GPU with drivers already installed. The installer wires up the NVIDIA Container Toolkit and a CDI spec; it does not install the GPU driver itself.

Install with the script

LabPod ships one public install script. It is a host setup script, not just an app installer - it installs Podman and rootless dependencies, adds the NVIDIA toolkit repo, generates the CDI spec, and installs the labpod binary and systemd units. It is idempotent: already-configured items are skipped, and re-running is safe.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

# Dry run - report what's missing, change nothing
curl -fsSL https://labpod.ai/install.sh | sudo bash -s -- --check

# Real install (latest release)
curl -fsSL https://labpod.ai/install.sh | sudo bash

# Install a pinned release instead of latest
curl -fsSL https://labpod.ai/install.sh | sudo bash -s -- --version v0.x.y

# Install host prerequisites only, skip the labpod service
curl -fsSL https://labpod.ai/install.sh | sudo bash -s -- --skip-app

# Run these as root
# Dry run - report what's missing, change nothing
curl -fsSL https://labpod.ai/install.sh | bash -s -- --check

# Real install (latest release)
curl -fsSL https://labpod.ai/install.sh | bash

# Install a pinned release instead of latest
curl -fsSL https://labpod.ai/install.sh | bash -s -- --version v0.x.y

# Install host prerequisites only, skip the labpod service
curl -fsSL https://labpod.ai/install.sh | bash -s -- --skip-app

Useful install options:

Option	What it does
--check	Dry run - report what would change, change nothing
--skip-socket	Skip enabling the target user’s podman.socket
--skip-app	Install host prerequisites only; skip the labpod binary and service
--skip-backup	On an upgrade, skip the automatic pre-upgrade DB backup
--bin <path>	Install a local labpod binary supplied for a support or recovery case
--admin-password-file <path>	Bootstrap the root LabPod password non-interactively
--gpu-sharing-lib <path>	Install an existing HAMi/libvgpu-compatible library
--with-hami	Build the HAMi sharing library with Podman and enable fractional GPU (off by default)
--uninstall	Remove LabPod-managed binaries, units, and generated assets while keeping config, data, license, and user accounts
--uninstall --purge	Also remove /etc/labpod and /var/lib/labpod data such as DB, backups, and license. It never removes researcher account-home or work data.
--uninstall --check	Dry-run uninstall; report what would be removed

Install from the release tarball

If your change-control process does not allow curl | bash, download the GitHub Release assets first, verify them, extract the tarball, then run the packaged installer:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

BASE="https://github.com/LabPod/labpod/releases/latest/download"

curl -fLO "${BASE}/labpod-linux-x86_64.tar.gz"
curl -fLO "${BASE}/labpod-linux-x86_64.tar.gz.sig"
curl -fLO "${BASE}/SHA256SUMS"

sha256sum -c SHA256SUMS

cat > labpod-artifact-pub.pem <<'EOF'
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEki5c/1B4iOqb16m6ljKHjnbbq5EP
D8mP4mNRCYrqniXLDAkDFbpGaMw6WqPBiCQUVqyvDzyL+pADdJTAdxcUSw==
-----END PUBLIC KEY-----
EOF

openssl dgst -sha256 \
  -verify labpod-artifact-pub.pem \
  -signature labpod-linux-x86_64.tar.gz.sig \
  labpod-linux-x86_64.tar.gz

mkdir labpod-release
tar -xzf labpod-linux-x86_64.tar.gz -C labpod-release

sudo bash labpod-release/scripts/install.sh

# Run these as root
BASE="https://github.com/LabPod/labpod/releases/latest/download"

curl -fLO "${BASE}/labpod-linux-x86_64.tar.gz"
curl -fLO "${BASE}/labpod-linux-x86_64.tar.gz.sig"
curl -fLO "${BASE}/SHA256SUMS"

sha256sum -c SHA256SUMS

cat > labpod-artifact-pub.pem <<'EOF'
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEki5c/1B4iOqb16m6ljKHjnbbq5EP
D8mP4mNRCYrqniXLDAkDFbpGaMw6WqPBiCQUVqyvDzyL+pADdJTAdxcUSw==
-----END PUBLIC KEY-----
EOF

openssl dgst -sha256 \
  -verify labpod-artifact-pub.pem \
  -signature labpod-linux-x86_64.tar.gz.sig \
  labpod-linux-x86_64.tar.gz

mkdir labpod-release
tar -xzf labpod-linux-x86_64.tar.gz -C labpod-release

bash labpod-release/scripts/install.sh

To install a pinned version instead, set BASE to a versioned release URL such as https://github.com/LabPod/labpod/releases/download/v0.1.0. You can pass the same installer options after the script path, for example sudo bash labpod-release/scripts/install.sh --check.

What the script does:

1. Detects the OS (apt vs dnf).
2. Installs podman and rootless dependencies (only if missing).
3. Adds /etc/subuid and /etc/subgid entries for the target user (only if missing).
4. Enables systemd linger for the user so rootless containers survive logout.
5. Enables podman.socket for the user.
6. Validates the environment: cgroup mode (v2 recommended; v1 runs degraded), user namespaces, etc.
7. On NVIDIA hosts, installs the GPU stack (NVIDIA Container Toolkit + CDI). Fractional GPU sharing (HAMi/libvgpu) is off by default — pass --with-hami to build and enable it.
8. Installs the labpod binary to /usr/local/bin/labpod, seeds /etc/labpod/labpod.env, and registers labpod.service.
9. Installs the workspace helper tree under /opt/labpod/inject (tmux, labpod-monitor, terminfo, and home skeleton files).
10. Fills in any missing default env keys and prepares the root-managed shared-image store when it is configured. Each researcher still receives their own rootless image copy before a workspace starts.
11. Installs labpod-backup.timer / labpod-backup.service for a daily SQLite snapshot in /var/lib/labpod/backups/.

cgroup v1 runs in a degraded mode

On a cgroup v1 host, CPU/memory quotas are not enforced (the workspace still starts, but without --cpus/--memory limits). GPU allocation is enforced either way; disk is measured but not blocked. cgroup v2 is strongly recommended.

First boot

The install script already initializes the database, sets the root admin password, and starts the service for you - you don’t need to run these by hand. During the real install (not --check), it prompts on the terminal for the root LabPod admin password (or reads one non-interactively from --admin-password-file <path>), then runs the schema migration, writes the password, and does systemctl enable --now labpod.

If you ever need to redo one of these steps manually - for example after --skip-app, or to recover from a stuck install - put --db after admin:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

# Apply the database schema
sudo labpod admin --db /var/lib/labpod/labpod.db migrate

# Set (or reset) the root LabPod admin password
sudo labpod admin --db /var/lib/labpod/labpod.db set-password root

# Enable and start the service
sudo systemctl enable --now labpod

# Run these as root
# Apply the database schema
labpod admin --db /var/lib/labpod/labpod.db migrate

# Set (or reset) the root LabPod admin password
labpod admin --db /var/lib/labpod/labpod.db set-password root

# Enable and start the service
systemctl enable --now labpod

JWT secret

Production requires LABPOD_JWT_SECRET (32+ bytes) in /etc/labpod/labpod.env - the server refuses to start without it. The installer generates a strong secret automatically and writes it to the env file, so you don’t need to set one yourself. Rotating it later logs everyone out - see Secret rotation.

Verify

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

systemctl status labpod
curl -s http://127.0.0.1:24680/api/health
curl -s http://127.0.0.1:24680/api/version      # short git SHA of the running binary
sudo labpod admin doctor                         # check host prerequisites, GPU sharing runtime, GPU inspector, …

# Run these as root
systemctl status labpod
curl -s http://127.0.0.1:24680/api/health
curl -s http://127.0.0.1:24680/api/version      # short git SHA of the running binary
labpod admin doctor                         # check host prerequisites, GPU sharing runtime, GPU inspector, …

doctor is your friend whenever something looks off - it checks host prerequisites and reports what to fix. For the full workstation preflight, use the install script’s --check mode.

You can now open http://<host>:24680 in a browser and log in as root. LabPod also uses the adjacent port, 24681 by default, as the workspace-application gateway. Allow both ports through the LAN firewall or VPN. Researchers start from the platform URL only; LabPod redirects workspace apps to the gateway as needed. See Workspace gateway before putting LabPod behind a reverse proxy.

Trial

If no signed license is installed, LabPod runs with the built-in 90-day trial entitlement. See Licensing for the trial limits and the labpod admin license commands.

Next steps

• Users & quotas - create researcher accounts and set per-user limits.
• GPU configuration - enable fractional GPU sharing or MIG.
• Templates & shared mounts - register images and mount shared datasets.
• Backups & restore - the daily timer and how to restore.
• Security & hardening - TLS, port guard, and the trust boundary.
• Workspace gateway - the paired browser origins and firewall or reverse-proxy requirements.