How to create a template

A template is the recipe LabPod uses when it creates a workspace. It records the image, app launchers, default CPU and memory, GPU preference, environment variables, and the README shown on the create screen.

README previews support Markdown tables and fenced code blocks. Wide tables and long commands scroll within the preview, so keep installation commands fenced and use a table when comparing template variants.

Use a private template when you need a repeatable environment for your own work. Admins can create global templates for everyone from /admin/templates; regular users create private templates from Templates → My templates.

The My images tab lists images before optional active-container, reclaim, sharing, and untracked-container checks. Choose Manage only when you need those details. My templates also appears before reusable global presets finish loading, which keeps both areas usable on a large or busy host.

Create a template from an existing image

Use this path when the image already exists in a registry or in your rootless Podman image store.

1. Open Templates. The page opens on My templates.
2. Click New template.
3. Fill in Name and Image. Example: docker.io/pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime.
4. Set Default CPU and Default memory to sensible starting values.
5. Add launchers in the Ports section. Use Import launcher when a matching catalog launcher exists.
6. Add template-level environment variables if every workspace from this template should receive them.
7. Click Create template.

Your template appears in the My templates tab and under My templates on the create-workspace screen. Only your account can edit it or create workspaces from it.

Clone a bundle and edit the Dockerfile

Use Clone when someone gave you a .tar LabPod bundle and you want to modify the Dockerfile or build context before using it.

1. Open Templates → My templates.
2. Click Import bundle.
3. Choose the .tar bundle file.
4. Review the preview. If it contains a Dockerfile, LabPod shows the Dockerfile and any context files in the preview.
5. Optionally change Display name.
6. Click Clone (edit, then build).

LabPod creates a disabled private template and writes the editable build context under:

~/work/.labpod/context/<template-id>/

The directory normally contains:

Dockerfile
requirements.txt
other files copied by the Dockerfile

To edit it:

1. Select the cloned template in My templates.
2. Click Edit files.
3. Open Dockerfile in the file manager, switch to edit mode, change it, and save.
4. Edit any copied files such as requirements.txt the same way.

To build it:

1. Return to My templates.
2. Select the cloned template.
3. Click Build.
4. Open My build history if you want to watch the build log.
5. After the build succeeds, return to the template and click Save to enable launching.

The build is template-keyed: LabPod reads the Dockerfile from ~/work/.labpod/context/<template-id>/ and builds the image tag stored on the template. You do not provide a separate build path.

Import a bundle as-is

Use Import when you trust the bundle and want to use it without modifying the Dockerfile.

1. Open Templates → My templates.
2. Click Import bundle.
3. Choose the .tar file and review the preview.
4. If the bundle has a Dockerfile, leave Build now checked to build immediately.
5. Click Import (build now).
6. When the build succeeds, select the template and click Save to enable launching.

If you uncheck Build now, LabPod registers the template and preserves its context. Build it later from the template’s Build button before creating a workspace from it.

Export a template

Use export to share a template with another LabPod user or another LabPod server.

1. Open Templates → My templates.
2. Select a template.
3. Click Export.

The downloaded bundle includes the template metadata, README, and, when available, the Dockerfile and build context. It does not include your /work files or workspace home.

What to put in the Dockerfile

Put system packages, Python packages, CUDA-compatible libraries, app servers, and command-line tools in the Dockerfile. Keep project data, notebooks, checkpoints, and large datasets in /work or shared mounts.

Example:

FROM docker.io/pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime

RUN apt-get update \
    && apt-get install -y --no-install-recommends git curl \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir jupyterlab tensorboard streamlit gradio

WORKDIR /work

After a workspace starts, LabPod mounts your persistent ~/work as /work, so files baked into /work by the image can be hidden by the mount. Put reusable code in another image path, or keep it in the cloned context and copy it into a path such as /opt/project-template.