System architecture
LabPod is designed for labs that want a managed GPU workstation without operating a cluster, external database, or separate control plane. The architecture keeps the moving parts small: one LabPod service, one local database file, and rootless Podman containers owned by real Linux users.
At a glance
Section titled “At a glance”Deployment model
Section titled “Deployment model”LabPod runs as a single service on the workstation. The web UI is embedded in the binary, so there is no separate frontend server to operate. The database is SQLite, stored as a local file and covered by LabPod’s backup and restore flow.
This shape is intentional: fewer services means fewer credentials, fewer upgrade steps, and less operational overhead for a lab workstation.
Linux user mapping
Section titled “Linux user mapping”Each LabPod user maps to a Linux account on the host. Workspace containers run as that Linux account through rootless Podman, so files created inside a workspace are owned by the same user on the host.
This model keeps storage behavior predictable for SSH access, shared datasets, backups, and
existing lab scripts. The LabPod root administrator account manages the system but does
not own user workspaces.
Workspace lifecycle
Section titled “Workspace lifecycle”A workspace is a persistent container. Starting a workspace creates or resumes the container with its CPU, memory, disk, mount, environment, and GPU policy applied. Stopping a workspace releases compute resources while preserving the user’s configured persistent storage.
Apps such as JupyterLab, code-server, TensorBoard, MLflow, and LabPod Terminal run inside the workspace. They can be started, stopped, or restarted independently without recreating the container.
Authenticated proxy
Section titled “Authenticated proxy”Researchers do not connect directly to random container ports. LabPod exposes workspace apps through an authenticated workspace gateway on a browser origin separate from the platform UI and API:
- Session cookies are checked before traffic is forwarded.
- Workspace app URLs are routed by workspace ID and app name.
- WebSocket traffic for terminal and live monitoring uses the same authenticated path.
- HTTP activity is recorded for resource visibility and idle indicators.
With the default listener, the platform is on port 24680 and the workspace gateway is on 24681.
The platform redirects /ws/ requests to the gateway, which rejects UI and API routes. This keeps
container-supplied browser code from using a LabPod session to read or change platform data.
See Workspace gateway for firewall and reverse-proxy deployment.
This keeps browser access consistent and avoids exposing per-workspace services directly on the network.
Monitoring and usage
Section titled “Monitoring and usage”LabPod reports live CPU, memory, GPU, process, disk, and usage data in the operator UI. It uses workspace-local telemetry for per-workspace metrics and host-side checks for cross-workspace signals such as GPU occupancy and image storage.
Usage samples and rollups are stored locally, so operators can inspect active load, export usage reports, and identify idle or resource-heavy workspaces without adding a separate metrics stack.
GPU access
Section titled “GPU access”GPU policy is configured per physical GPU by the operator.
| Mode | How access is granted |
|---|---|
| Whole GPU | Podman receives a Container Device Interface (CDI) device assignment for the selected GPU |
| Fractional GPU | A software sharing runtime limits the workspace’s GPU memory and compute share |
| MIG slice | Podman receives a CDI device assignment for the selected MIG slice |
LabPod checks quotas and current allocation before starting GPU workspaces. The goal is explicit, operator-controlled access rather than a shared free-for-all.
Security posture
Section titled “Security posture”LabPod’s default posture is local-account-based and rootless:
- Workspace containers run as non-root Linux users.
- Users do not receive access to a Docker socket or root-equivalent daemon.
- Sessions are stored server-side and sent as HttpOnly cookies.
- Passwords are stored using a memory-hard password hashing algorithm.
- Administrative actions and workspace lifecycle events are recorded in the audit log.
For network-facing deployments, use TLS and the hardening settings described in Security & hardening.
Why this architecture
Section titled “Why this architecture”LabPod is built for interactive single-node GPU workstations. Quotas, visibility, and operator controls fit that environment better than a cluster scheduler or queue. Podman keeps containers aligned with Linux account ownership, and the single-binary model keeps daily operations approachable for small teams.