Core concepts

The vocabulary every other page assumes. Each term links to the page that covers it in depth.

Workspace

A workspace is a persistent Podman container assigned to one user, with CPU, memory, and GPU quotas plus an advisory disk alert. It stays running until the user or an admin stops it; LabPod does not auto-stop idle workspaces.

Each workspace has:

A workspace template that defines its container image and available apps.
Resource limits (CPU cores, memory, GPU) and an advisory disk alert.
A set of launchers (apps) that the user starts or stops inside the running container.
A private HOME volume that persists across stop/start cycles.
A /work bind mount pointing to ~/work on the host - code and data survive workspace deletion.

→ Workspace lifecycle

Launcher

A launcher is a service started inside a running workspace via podman exec. Starting or stopping a launcher does not restart the workspace or affect other launchers.

Built-in launchers include JupyterLab, code-server (VS Code in the browser), LabPod Terminal, TensorBoard, MLflow, Aim, RStudio Server, ComfyUI, and MATLAB (disabled by default; an operator must opt in and bring a MathWorks license). Which launchers are available depends on the workspace template.

→ Apps & launchers

Workspace template

A workspace template is a container image plus launcher configuration and resource defaults. The admin registers global workspace templates available to everyone; users can also create their own and share them via export/import bundles. Established API and CLI commands and fields retain the shorter technical identifiers template and workspace_type; the product term remains workspace template.

→ Workspace templates & shared mounts

Shared mount

An admin-configured host path (for example /data/datasets, typically read-only) mounted into every workspace. Used to share large datasets across all users without duplicating them.

→ Workspace templates & shared mounts

GPU modes

LabPod supports three GPU allocation modes, configured per-GPU by the admin:

Mode	What it means
Whole GPU	One full NVIDIA GPU per workspace, allocated via Container Device Interface (CDI)
Fractional GPU	Multiple workspaces share one GPU via software partitioning
MIG slice	Hardware-partitioned slice on an A100, H100, H200, or B100 (not yet verified on real MIG hardware)

A workspace that requests no GPU runs on CPU only.

→ Using the GPU · GPU configuration

Rootless Podman and `keep-id`

Every workspace runs as the owner’s Linux account using rootless Podman. The --userns keep-id flag ensures the host UID matches the container UID, so files created inside a workspace have natural ownership on the host and are accessible over SSH without confusion.

Reverse proxy and `/ws/` URLs

The LabPod server proxies all workspace traffic. When you click Open on a launcher, the URL looks like http://<host>:24681/ws/<workspace-id>/jupyter/. All traffic flows through your LabPod session cookie - no separate login for individual apps.

User-declared ports

Inside a workspace you can declare named ports for custom services (Gradio, Streamlit, etc.). Each declared port gets a /ws/<id>/_user/<name>/ proxy path accessible from your browser. Launchers remain at /ws/<id>/<launcher>/, so a declared port and launcher may use the same name.

→ Extra apps & ports

Discovered containers

Containers you start directly with Podman (outside LabPod) are not LabPod workspaces. LabPod may include them in read-only safety and capacity views so their CPU, memory, GPU, and process usage is not mistaken for free capacity. It does not provide proxy URLs, launchers, terminals, logs, user-declared ports, or lifecycle actions for these containers. Use the LabPod UI or labpod ws create to create a supported workspace.

Idle nudge

When a workspace has been idle for more than a configurable number of days, the home page shows a badge. This is display-only; LabPod does not auto-stop idle workspaces.