Persistent Docker
Overview
Persistent Docker lets developers keep pulled Docker images on their workspace’s persistent volume. With the feature enabled, images that a developer downloads inside a workspace are cached under /home/developer/ and remain available after the workspace is paused, restarted, or updated.
Without Persistent Docker, the Docker data root (/var/lib/docker) lives on the workspace’s ephemeral root filesystem. Every time the workspace container is recreated — on pause/resume, restart, or image update — the Docker image cache is discarded and any image referenced by the developer’s tooling has to be downloaded and unpacked again.
What problem it solves
Pulling images on every workspace start can dominate ramp-up time, especially when:
- A developer’s workflow depends on several large images (databases, browsers for end-to-end tests, language toolchains, CI runners).
- Images have many layers and the workspace is sized with only one or two CPUs, so layers can only be unpacked sequentially.
- The registry rate-limits or throttles pulls (for example, public Docker Hub limits per IP or per organization).
- The cluster has limited or metered egress to the registry.
In environments where multiple images are pulled per session, the cost can be significant — a workspace that takes seconds to resume can still leave the developer waiting 20+ minutes before their tooling is usable.
Persistent Docker eliminates the redundant pull-and-unpack work after the first time an image is used. The workspace itself still starts in the same amount of time; what improves is the time-to-productive — how long until the developer’s Docker-based tooling is actually ready.
Note:
Persistent Docker caches images, not container state. Data written inside a running container is still discarded when the container is removed. To persist data produced by a container (a database file, application state, generated artifacts), mount a directory under
/home/developer/into the container as a Docker volume. See What persists in an SDS Workspace.
How to get access
Persistent Docker is gated by a license feature flag. By default, the flag is not enabled on customer licenses.
To request access:
- Contact Citrix Support or your account team and ask for Persistent Docker to be enabled on your SDS license.
- Citrix enables the feature flag on the license record for your domain.
- A platform admin in your SDS environment refreshes the license so the new flag is picked up:
- Online license — Open the SDS admin console, go to System Configuration → License, and select Upload New License → Online License. The refreshed license includes the Persistent Docker feature flag.
- Air-gapped (file) license — Citrix provides a new license file. Upload it under System Configuration → License → Upload New License.
After the license refresh, Persistent Docker appears as a new entry in the platform feature flags list, alongside other gated features such as GPU Support.
Configure Persistent Docker in SDS
Once the feature flag is visible in your environment, a platform admin controls who can use it.
Enable the feature flag
- Sign in to the SDS admin console as a platform admin.
- Go to System Configuration → Platform Features.
- Locate Persistent Docker in the list of feature flags.
- Choose the rollout scope:
- Enabled — All developers on the platform get Persistent Docker.
- Enabled for selected users — Only the users, domains, or groups you specify get Persistent Docker. Add entries under Users, Domains, and Groups as needed.
- Save the configuration.
Apply the change to running workspaces
The feature is applied at workspace start. A developer with a workspace that was already running when the flag was enabled must do one of the following to start caching images:
- Pause and resume the workspace, or
- Restart the workspace, or
- Update the workspace.
New workspaces created after the flag is enabled automatically use Persistent Docker.
Plan for additional persistent-volume usage
Persistent Docker stores image layers on the workspace’s persistent volume. Because developers commonly depend on multiple images — and often multiple versions of the same image — the persistent volume fills up considerably faster than without the feature.
Before enabling Persistent Docker broadly, review your workspace specifications:
- Go to System Configuration → Workspace Specifications.
- Either:
- Increase the default disk size on the specifications used by developers who will get Persistent Docker, or
- Enable Allow users to increase storage on those specifications so developers can self-size their persistent volume as their image cache grows.
If a developer’s persistent volume fills up, image pulls and other workspace operations will start to fail. Plan headroom accordingly.
Verify Persistent Docker is active
A developer can confirm the cache is persisting across restarts:
- Open a workspace terminal.
-
Pull or run an image, for example:
docker pull postgres:16 docker images <!--NeedCopy--> - Confirm the image is listed by
docker images. - Pause and resume the workspace.
-
Open a terminal again and run:
docker images <!--NeedCopy-->Expected result: The
postgres:16image is still listed without being re-pulled.
If the cache is empty after a restart, Persistent Docker is not active for that developer. Confirm with a platform admin that the feature flag is enabled and that the developer is in scope (user, domain, or group).
How to persist container data (Docker volumes)
Persistent Docker only caches images. Anything a container writes to its own filesystem is still lost when the container is removed. This is standard Docker behavior; SDS does not change it.
To persist data produced by a container, mount a folder from /home/developer/ into the container as a volume. For example, to run Postgres with its data directory backed by your persistent volume:
mkdir -p ~/postgres-data
docker run -d \
--name pg \
-e POSTGRES_PASSWORD=secret \
-v ~/postgres-data:/var/lib/postgresql/data \
postgres:16
<!--NeedCopy-->
The database files live under ~/postgres-data, which is on the persistent volume, so they survive workspace restarts. Use the same pattern for any other stateful container: identify the path the application writes to, and mount a directory from /home/developer/ to that path.
For a complete overview of what survives across workspace restarts, see What persists in an SDS Workspace.