Create Image Page

The Create Image form with the secondary sidebar, showing General settings, Build host, and the Image configuration tabs.

The Create Image page builds the container image that workspaces deploy from. The form is split into sections, navigable from the secondary sidebar. The same form is reused for editing on the Image Details page and for saving an image as a template.

A submit-mode button lets you choose Save or Save as template when creating.

General settings

• Name: the descriptive name Trailer uses for the image.
• Description: optional free text.

Build host

Select the host that builds the image. You can only pick a host where you have permission to create images. If the image is not pushed to a registry, the built image stays only on that host.

See Hosts for managing hosts.

Image configuration

A tab group selects how the image is produced:

• Generate Dockerfile (default): Trailer generates a Dockerfile from a base image plus the packages, environments, and services you select.
• Pull an image: use an existing image from Docker Hub or another registry, no build step.
• Write Dockerfile: author a Dockerfile by hand in the editor.

Generate Dockerfile

Pick a Workspace base image (defaults to ubuntu:24.04). Advanced settings expose:

• Image name: the resulting Docker reference. Auto-derived from the image name until you edit it.
• Pull base image: force-pull the base image before building even if it is present locally.
• Squash final image: squash the build into a single layer to reduce size. Seeded from the build host default. Turn it off only on storage-constrained hosts.
• Push after build: push to the registry implied by the image name after a successful build.
• Enabled: only enabled images can back workspaces.

Pull an image

Select the image to pull. Advanced settings expose Push after build and Enabled.

Write Dockerfile

Write the Dockerfile in the editor. The same advanced settings as Generate Dockerfile apply.

Avoid VOLUME in a hand-written Dockerfile

Do not declare VOLUME in your Dockerfile. It causes two surprises.

During the build, any change written to a path after its VOLUME line is silently discarded. That is standard Docker build behavior, not something Trailer adds, and it is a common source of “my files vanished” confusion.

At runtime the path is backed by an anonymous volume. Trailer removes a workspace’s anonymous volumes whenever the workspace is removed or recreated, so anything written under a VOLUME path is lost on the next recreate. If a path needs to persist, attach a volume at that mount point instead of declaring VOLUME.

The Squash final image setting does not remove a VOLUME you write here. That stripping only happens for generated images, where it drops the base image’s own VOLUME declarations.

Python packages and environments

Shown only for Generate Dockerfile. Define named conda environments and choose conda and pypi packages for each. Trailer resolves and installs them into the image. These environments can later be targeted by startup commands. See Software environments and packages for how this works and what it is built on.

This section also has a CUDA version selector for building GPU-enabled packages such as pytorch-gpu. It only affects conda packages, not pypi packages, and its options are color-coded against the build host’s GPU driver. See Choosing a CUDA version for image builds for how to pick one.

Services

Shown for generated and hand-written Dockerfiles (not for pulled images). Adds pre-configured services and the optional Virtual Desktop. See the dedicated section below.

User configuration

Shown for non-pulled images, except Windows VDI. Configures the workspace container user: optional uid, user name, gid, and group name (uid/gid range 0 to 65535).

Startup applications

Shown for non-pulled images. Define one or more commands to run when a workspace built from this image starts. Each command can be bound to one of your defined environments, so it runs with that environment’s packages on its path.

• One command: it runs as the workspace’s main process.
• Multiple commands: Trailer runs them all at once and keeps them running. If one exits it is restarted automatically, and the output of every command is merged into the workspace logs.

Defining startup here is the recommended way to control boot behavior. Prefer it over the per-workspace startup override, which replaces all of this at once. See the startup note on Create Workspace.

Multiple startup commands need a glibc base image

Running more than one startup command requires a base image built on the standard GNU C library (glibc), such as an Ubuntu- or Debian-based image. The mechanism that runs and keeps several commands alive relies on your packaged software environment, and that environment can only be activated on a glibc base image. On a base image that uses a different C library (Alpine and other musl-based images), the environment cannot be activated, so define at most one startup command. For any image that needs multiple startup commands, choose a glibc-based base image. See Software environments and packages for why.

Files

Shown for non-pulled images. Attach files that should be present in the image. Each file entry has a source and a destination path inside the image:

• From archive: pick a file already uploaded to Trailer.
• Upload: upload a new file (max 5 MB each).
• External URL: reference a URL.

Up to 99 files per image. The Path in image field sets where the file lands. For Windows VDI images this field becomes Path on C: drive. See Files.

Files are placed into the image with the same file-add step a Dockerfile uses on a Docker build host, so the usual behaviors apply:

• An uploaded file is copied to the destination. If it is a tar archive (including gzip, bzip2, or xz), it is unpacked into the destination directory instead of copied as a single file.
• An external URL is fetched when the image builds. A plain file URL is downloaded to the destination as-is. It is not unpacked, even if it is an archive.
• A Git repository URL is cloned into the destination. This requires a build host running the modern Docker build engine. On older engines URL downloads and archive unpacking still work, but Git sources do not.

Note

The behaviors above apply to normal (Docker-based) image builds. Windows VDI files are injected into the Windows disk image by a separate step and are always placed as-is at their destination, so archive unpacking and URL or Git handling do not apply to them. Build backends added in the future may also handle file sources differently.

Permissions

When creating, you can grant other users view, modify, and delete access to the image. On the Image Details page permissions are managed in their own section. See Permissions and access control for the full model.

Virtual Desktop (VDI) options

The Services section can turn the image into a Virtual Desktop image. Toggle Virtual Desktop, then configure it.

The Operating system dropdown drives everything else. Linux options are Alpine, Arch, Debian, Enterprise Linux, Fedora, and Ubuntu. Selecting Windows switches the form into Windows VDI mode.

Linux VDI

• Desktop environment: i3, KDE, MATE, or Xfce. Only the environments valid for the chosen OS are offered.
• Keyboard layout and System language.
• Desktop applications: GUI apps installed into the desktop (for example Firefox, GIMP, Blender, VS Code). Selecting more than one desktop application automatically enables Virtual Desktop and keeps it locked on: you cannot turn Virtual Desktop off while more than one is selected, since multiple graphical apps need a desktop to run in. Reducing the selection back to one or none releases the lock (when Virtual Desktop was enabled this way).
• General applications: package-manager apps such as Code Server, FFmpeg, Jupyter Lab, and Nginx. These do not require a desktop.

Windows VDI

Selecting Windows replaces the Desktop environment dropdown with a Windows edition dropdown and shows username and password fields. Desktop apps, general apps, and the image-level user configuration do not apply to Windows images.

• Windows edition: Windows 11 Pro, 11 LTSC, 11 Enterprise, 10 Pro, 10 LTSC, 10 Enterprise, Windows Server 2025, or Windows Server 2022.
• Username: the local administrator account name.
• Password: the local administrator password. On edit, an already-set password shows a hint and is preserved if left blank.
• Keyboard layout and System language.

Selecting services applies a server-side prefill to the rest of the form (for example the base image), so the form briefly disables saving until that prefill returns.

Related Pages

• Images - List of all images
• Image Details - Edit, build messages, permissions
• Image Templates - Reusable image configurations
• Files - Manage uploaded files
• Hosts - Build hosts