Update an existing container image

Last published : Oct 20, 2026
Related information
Build and manage custom workspace images for SecurSpaces

Overview

This article focuses on the platform workflow to update an existing container image so teams can reuse a consistent, preconfigured toolchain across workspaces. For day‑to‑day software persistence management, refer to the How to Maintain Persistent Changes in Your Workspace.

Why persistency matters

Container images define the baseline configuration of a development environment. Users create workspaces from an image as a blueprint, which helps prevent environment drift and speeds up onboarding.

Context: persistence and startup scripts

In SecurSpaces, only data in /home/developer is persistent by default. Changes outside that directory (for example OS-level package installations) do not persist across workspace restarts.
The best practice is to keep shared tooling (e.g. across a team, a project, etc.) in a workspace base image, so teams get a consistent toolchain across workspaces. Use startup scripts only for individual customization, e.g. user-specific.
For details about workspaces' persistence model and how to make subsequent installations persistent, refer to How to Maintain Persistent Changes in Your Workspace.

Manage container images (Resources → Container images)

Permission:
To add a workspace image, you need the Resources permission set to Import.
Images are imported from a registry (public or private). Private registries require credentials; public registries do not.

View container images

The Container images panel (under Resources → Container images) displays the images available in the selected scope (project, organization, or platform). You can search for images or filter those currently used in workspaces.

Add a container image

To add an image:
  1. Go to Resources → Container Images for your project.
  2. You can add container images at the project, organization, or platform scope (depending on your permissions)
  3. Select Add Image.
  4. Provide URL, Image Name, and Image Tag. Optionally, set Private Registry and Attach Asset Information.
Warning:
For image requirements, see Container image requirements.

(Optional) Sample images

If you want examples of workspace images, Citrix publishes both Dockerfiles and prebuilt images:

Make an environment persistent for your team

There are two common ways to standardize tooling for a team:

Option 1: Create a new workspace image (where supported)

In product deployments, Citrix SecurSpaces™ can transform a startup script into a new workspace image automatically whenever needed. Feature availability can differ between environments.

Option 2: Start from an existing image and standardize configuration with startup scripts

Use this option when you want a reliable baseline and only need to apply configuration or smaller installations at workspace startup. Startup scripts can run pre-start or post-start depending on whether the workspace must wait for them.

Points of consideration

  • Only /home/developer is persistent between workspace restarts. Plan installations accordingly (image, user-space tooling, or startup script).
  • Image prerequisites: verify SSH, GIT, GIT LFS, and developer UID 1000 before sharing an image broadly.
  • Governance: consider restricting allowed registries and configuring private registries centrally (Image URL Constraints and Create Image Registry).

References

FAQ

  • Why did my installed tools disappear after a restart?
    Only /home/developer is persistent. Anything installed elsewhere must be baked into the image or re-applied at startup.
  • What is the fastest way to onboard a team?
    Provide a workspace image that includes the shared toolchain and keep only dynamic configuration in startup scripts.
  • When should I use post-start?
    Use post-start for heavy work so the workspace becomes available quickly while setup continues in the background.