Users & quotas

import { Steps } from ‘@astrojs/starlight/components’;

LabPod manages two things per user: a LabPod account (login credentials and quotas) and a Linux account on the host (where containers run). These are related but separate.

Creating a user

From the admin UI

Open /admin/users → New user. Fill in the username and an initial password. LabPod provisions a Linux account automatically if one doesn’t already exist.

From the CLI

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

# Interactive password prompt
sudo labpod admin --db /var/lib/labpod/labpod.db create-user alice

# Or pipe the password (for automation)
printf '%s\n' 'initial-password' | sudo labpod admin --db /var/lib/labpod/labpod.db create-user alice

# Run these as root
# Interactive password prompt
labpod admin --db /var/lib/labpod/labpod.db create-user alice

# Or pipe the password (for automation)
printf '%s\n' 'initial-password' | labpod admin --db /var/lib/labpod/labpod.db create-user alice

When LabPod creates a new Linux account it runs:

1. useradd -m -s /bin/bash <username> - creates the account and home directory.
2. chpasswd - sets the initial Linux password (same as the LabPod password at creation time).
3. loginctl enable-linger <username> - keeps the user’s systemd slice running after logout, so rootless containers survive a browser disconnect.
4. Creates the workspace-private and work directories beneath the configured account-home and work bases. With the defaults these are /home/<username>/workspaces/ and /home/<username>/work/.
5. Creates /shared/<username>/ (readable by all users) if the /shared root exists.

If a Linux account with that username already exists, LabPod adopts it only when its configured home is already beneath LABPOD_FILEOP_HOME_BASE. It then enables linger and creates required workspace directories, but never modifies the existing Linux password. An account homed elsewhere is rejected with an explanation rather than being changed unexpectedly.

LabPod password vs. Linux password

These are fully independent credentials after account creation:

What	Where	Who can change it
LabPod password	LabPod database	User (Settings page), admin (set-password)
Linux password	Host /etc/shadow	Only the host admin, outside LabPod

Changing a LabPod password via the UI or set-password never modifies the Linux password. The Linux password is only set once, during the initial create-user call, and is otherwise LabPod’s concern.

Resetting a LabPod password

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin --db /var/lib/labpod/labpod.db set-password alice
# Or pipe:
printf '%s\n' 'new-password' | sudo labpod admin --db /var/lib/labpod/labpod.db set-password alice

# Run these as root
labpod admin --db /var/lib/labpod/labpod.db set-password alice
# Or pipe:
printf '%s\n' 'new-password' | labpod admin --db /var/lib/labpod/labpod.db set-password alice

Listing users

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin --db /var/lib/labpod/labpod.db list-users

# Run these as root
labpod admin --db /var/lib/labpod/labpod.db list-users

Roles

Role	How to identify	What they can do
Root admin	Username is root	Everything: user CRUD, templates, policies, images, audit logs, force-stop any workspace
Superuser	Superuser flag set	View all workspaces and resource usage; no mutations
Regular user	Default	Own workspaces, templates, and files only

Root cannot own workspaces

The root account can observe and force-stop workspaces but cannot create or start its own. Workspace containers run as their owner’s Linux account; root doesn’t have a user-mode container context. Use a separate regular user account if you need to test a workspace.

Admin authority boundary

An admin can:

• View and monitor any workspace.
• Force-stop any workspace (recorded in the audit log).

An admin cannot (without OS-level access):

• Enter another user’s terminal session.
• Start, edit, or launch apps in another user’s workspace.
• Delete another user’s workspace.
• View another user’s files via the LabPod file manager.

Per-user quotas

Quotas are set per user via /admin/policies:

Quota	What it limits
Max CPU	Total cores across all running workspaces
Max memory	Total RAM (GB) across all running workspaces
Max GPU fraction	Total GPU allocation (1.0 = one full GPU) across running workspaces
Max workspaces	Number of simultaneously running workspaces
Disk alert	Advisory GB threshold for the user’s account home and relocated work area

CPU, memory, GPU, and workspace-count quotas are enforced at workspace start time when their host support is effective. Disk use is measured and can raise an alert, but LabPod never blocks a write or a workspace start for disk use. Running workspaces are not stopped when an admin lowers a quota.

cgroup v1 hosts

On a cgroup v1 host, CPU and memory quotas are recorded but not enforced at the container level. GPU quotas still apply; disk use remains advisory. See Requirements.

Deleting a user

From the admin UI: removes the LabPod database record and revokes all sessions. The Linux account and home directory are preserved - LabPod never calls userdel. If you want to reclaim disk space, do so manually as a host admin.

Re-adding the same username later adopts the existing Linux account.