CLI

LabPod ships as a single binary with three command surfaces:

• labpod server - starts the HTTP server.
• labpod admin <subcommand> - bootstrap and break-glass operations.
• labpod login, labpod ws, labpod template, labpod image, and labpod token - signed-in user commands for a running LabPod server.

labpod --version    # print build SHA
labpod --help       # print usage

Database path resolution

Every command that opens SQLite resolves the database path in this order:

1. CLI --db <path> (placed after the subcommand)
2. LABPOD_DB environment variable in the current process
3. LABPOD_DB auto-loaded from /etc/labpod/labpod.env
4. labpod.db in the current working directory

For installed admin commands, use sudo on sudo-based hosts. On Rocky/RHEL systems where you usually work in a root shell, use the root-shell tab instead:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin --db /var/lib/labpod/labpod.db list-users
# or:
sudo labpod admin list-users    # auto-reads /etc/labpod/labpod.env

# Run these as root
labpod admin --db /var/lib/labpod/labpod.db list-users
# or:
labpod admin list-users    # auto-reads /etc/labpod/labpod.env

Check which path a command would use:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

labpod admin db-path
sudo labpod admin db-path

# Run these as root
labpod admin db-path

labpod server

labpod server [--db <path>] [--port <port>] [--dev]

Flag	Default	Notes
--db <path>	From env / labpod.db	Override the database path
--port <port>	24680	Override LABPOD_PORT
--dev	off	Enable localhost CORS, ephemeral JWT secret

The installed systemd service runs:

/usr/local/bin/labpod server

Configuration comes from /etc/labpod/labpod.env. See Environment variables for the full list.

Signed-in user commands

Use these commands from a workstation or the LabPod host to work with a running LabPod server. They use the permissions of the account that signs in, so they do not need sudo and cannot replace administrator commands.

Sign in and choose a server

labpod login https://lab-gpu.example.local --user kim
labpod whoami
labpod logout

The password is prompted for, or may be supplied on standard input for an interactive pipeline. The session is stored per server in ~/.config/labpod/client.json (directory mode 0700, file mode 0600), and the most recently used server becomes the default. Target another saved server with --server <url>.

Sessions expire after 7 days by default. An operator can change the server value with LABPOD_SESSION_TTL. Log in again when a command exits with code 3.

For a self-signed HTTPS server, get the fingerprint from the operator and pin it at login:

labpod login https://lab-gpu.example.local --user kim --tls-fingerprint <sha256>

The client verifies that pin on later connections. It does not provide an insecure TLS option.

Workspaces

labpod ws list
labpod ws capacity
labpod ws create --template tmpl-pytorch-jupyterlab --name train1 --gpu-count 1
labpod ws start <workspace-id>
labpod ws logs <workspace-id> --tail 200
labpod ws stop <workspace-id>
labpod ws delete <workspace-id> --yes

ws create sends only the resource flags you set, allowing the template defaults to apply. Run labpod ws --help for CPU, memory, GPU, environment-variable, launcher, and log options.

To run one non-interactive command in a running workspace you own, put the container command after --:

labpod ws exec <workspace-id> -- nvidia-smi -L
labpod ws exec <workspace-id> --timeout 600 -- bash train_prep.sh

Workspace execution is owner-only, including for administrators. It has a 300-second default timeout, a 600-second maximum, and a 256 KiB output limit. Detach long jobs with nohup or setsid, then inspect their output with ws logs or files in the workspace.

Templates and images

labpod template list
labpod template clone tmpl-pytorch-jupyterlab --name my-copy
labpod template export tmpl-pytorch-jupyterlab --out bundle.tar
labpod template import bundle.tar --build-later

labpod image list
labpod image status <template-id>
labpod image pull <template-id> --wait
labpod image build <template-id> --wait
labpod image builds

Use template create --file <spec.json|-> and template edit <id> --file <patch.json|-> when automating template definitions; - reads JSON from standard input. Imported templates land disabled for review. Dockerfile-backed clones and imports must be built before being enabled.

Starting a workspace never pulls or builds a missing image. Use image pull for a registry image or image build for a Dockerfile-backed template, then start the workspace again. image pull and image build use the registry and terms rules set by the server administrator.

Personal access tokens

Personal access tokens (PATs) let the CLI, scripts, and LLM agents authenticate to a LabPod server without an interactive password login. Create, list, and revoke them with labpod token:

labpod token create --name ci-runner              # prints the token ONCE
labpod token create --name nightly --expires 30   # custom expiry in days (365 maximum)
labpod token list
labpod token revoke <token-id>

A new token’s secret is printed once at creation and is never stored on the server, so copy it right away. The default lifetime is 90 days. Use a token in any of three ways:

export LABPOD_TOKEN=labpod_pat_...          # picked up automatically by client commands
labpod login https://lab-gpu.example.local --user kim --token   # save the PAT as this server's session
curl -H "Authorization: Bearer $LABPOD_TOKEN" https://lab-gpu.example.local/api/workspaces

A token carries the same permissions as the user who created it — it drives that user’s own workspaces, templates, and images, and never administrator operations. Managing tokens themselves always needs a password session (labpod login); a PAT cannot mint or revoke tokens.

You can also review and revoke your tokens in the browser under Settings → API tokens, which flags any token expiring within seven days. Creating a token is CLI-only, because the secret is shown a single time and never persisted.

JSON output and exit codes

Add --json to a client command when a script needs the raw API response:

labpod ws list --json
labpod ws create --template tmpl-pytorch-jupyterlab --json

template export is the exception because it writes a tar file and does not accept --json. Exit codes are 0 for success, 1 for an API or network error (or an aborted confirmation), 2 for invalid command usage, and 3 when the client is not signed in or its session expired.

labpod admin

labpod admin [--db <path>] <subcommand> [args]

Subcommand	What it does
migrate	Apply any pending database schema migrations (idempotent)
create-user <name>	Create a LabPod account; provisions Linux account if absent
set-password <name>	Rotate the LabPod password (DB only, not the Linux password)
list-users	Print all users with their superuser and disabled flags
db-path	Print the resolved database path for this invocation
doctor	Check host prerequisites and report what to fix
backup --out <path>	One-shot snapshot to an explicit file
backup --dir <dir> --retention <N>	Timestamped snapshot; prune to newest N
restore <path> [--yes]	Copy a snapshot onto the live DB (stop service first)
tls-fingerprint	Print SHA-256 fingerprint of the serving TLS certificate
template import <path.tar> (--owner <server_userid> | --global)	Import a host-local template bundle, disabled for review
license show	Show the resolved trial or signed-license entitlement
license request	Print the host activation request code
license verify <file>	Validate a license file without installing it
license install <file>	Verify and install a license file to LABPOD_LICENSE_PATH

create-user and set-password read the password interactively or from stdin when piped:

The examples below use sudo for Ubuntu-style administration. If you are already in a root shell, as is common on Rocky/RHEL systems, omit sudo.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

# Interactive
sudo labpod admin set-password alice

# Piped (automation)
printf '%s\n' 'new-password' | sudo labpod admin --db /var/lib/labpod/labpod.db set-password alice

# Run these as root
# Interactive
labpod admin set-password alice

# Piped (automation)
printf '%s\n' 'new-password' | labpod admin --db /var/lib/labpod/labpod.db set-password alice

License commands

Without an installed signed license, LabPod runs under the built-in 90-day trial. License files are installed locally with the admin CLI:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin license show
sudo labpod admin license request
sudo labpod admin license verify ./license.lic
sudo labpod admin license install ./license.lic

# Run these as root
labpod admin license show
labpod admin license request
labpod admin license verify ./license.lic
labpod admin license install ./license.lic

The shipped binary handles local request, verification, installation, and status display.

Template import command

Use this when a bundle already exists on the LabPod host and you want to import it without going through the browser upload flow:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin template import ./template.tar --global
sudo labpod admin template import ./template.tar --owner alice

# Run these as root
labpod admin template import ./template.tar --global
labpod admin template import ./template.tar --owner alice

--global creates a managed template visible to everyone after review. --owner creates a private template for that Linux-backed LabPod user. Imported templates are disabled by default.

Dockerfile bundles are not supported by the CLI because they require an image build. Import those from /admin/templates instead.

Common flows

Fresh production bootstrap:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin --db /var/lib/labpod/labpod.db migrate
sudo labpod admin --db /var/lib/labpod/labpod.db set-password root
sudo systemctl enable --now labpod

# Run these as root
labpod admin --db /var/lib/labpod/labpod.db migrate
labpod admin --db /var/lib/labpod/labpod.db set-password root
systemctl enable --now labpod

Inspect the running service:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

systemctl status labpod
journalctl -u labpod -f
curl http://127.0.0.1:24680/api/health
curl http://127.0.0.1:24680/api/version
sudo labpod admin doctor

# Run these as root
systemctl status labpod
journalctl -u labpod -f
curl http://127.0.0.1:24680/api/health
curl http://127.0.0.1:24680/api/version
labpod admin doctor

See Environment variables and Runtime settings.