Skip to content
Trailer.devDocumentation

Search is only available in production builds. Try building and previewing the site to test it out locally.

Workspace Snapshots

The Snapshot Workspace page showing the snapshot image name field (prefilled with the source image name plus a timestamp) and the Create snapshot button.

A snapshot captures the live filesystem of a running workspace and saves it as a new, reusable image. The agent commits the workspace container as it is, so any packages installed, files written, or changes made inside the running container become part of the new image. You can then create new workspaces from that image.

What a snapshot captures

Section titled “What a snapshot captures”

The snapshot is a commit of the running container, so it includes the container’s writable filesystem at the moment of the snapshot. The new image record is cloned from the workspace’s source image, so it keeps the same base configuration (base image, environments, services, files, and other settings) and adds the committed filesystem on top.

A snapshot does not capture:

  • Volume contents. Attached volumes are external mounts, not part of the container filesystem, so their data is not committed into the image.
  • Running process state. The result is an image, not a live checkpoint. New workspaces created from it start fresh.

The container is paused briefly while the agent commits it, then resumes.

Requirements

Section titled “Requirements”

The Snapshot action is only available when all of the following are true:

  • The workspace status is Running.
  • The host the workspace runs on is online and reports the snapshotter capability. The Docker runtime backend supports snapshotting.
  • You can view the workspace. The snapshot endpoint checks view access, not modify access.

If the host does not support snapshotting, the page shows a notice instead of the form.

Creating a snapshot

Section titled “Creating a snapshot”
  1. Open the workspace and use the Snapshot action (available from the workspace actions on the Workspace Details page), or navigate to the workspace’s snapshot page directly.
  2. Enter a name for the new image. The field is prefilled with the source image name plus a timestamp suffix. You can change it.
  3. Select Create snapshot.

The server creates a new image record in the Snapshotting state and signals the agent. While the snapshot runs, the workspace shows the Snapshotting status and cannot be updated, started, stopped, or deleted. Only one snapshot can be in progress per workspace at a time.

When the agent finishes committing the container, the new image moves to the Build finished state with a fresh digest, and the workspace returns to its previous status. The UI navigates you to the new image’s detail page.

Snapshot lifecycle

Section titled “Snapshot lifecycle”
flowchart TD
  A[Running workspace] -->|Create snapshot| B[New image record: Snapshotting]
  B --> C[Agent commits the running container]
  C --> D[Image: Build finished with new digest]
  D --> E[Create new workspaces from the image]
  C -.->|Workspace shows Snapshotting status,<br/>reverts when done| A
Section titled “Related Pages”