Skip to main content

Rolling Image Management

Rolling Image Management lets you control how and when Kasm images receive updates by choosing rolling or static tags. Rolling tags pull the latest builds on startup to keep security fixes and patches current, while static tags lock to a specific release for change control. Kasm provides a rolling utility to manage rolling images that Kasm uses to run.

The default behavior of the Kasm installer is to use rolling images. To install Kasm using static images, pass in the -f or --use-static-images arguments during the installation process.

sudo bash kasm_release/install.sh -f

The Kasm installer also accepts a specific dated rolling image tag to use during the initial install. To specify a dated rolling image, pass in the -F or --use-tag arguments and the dated rolling image tag desired during the installation process. If the -F or --use-tag arguments are used without specifying a dated rolling tag, the installer defaults to the dated rolling tag matching its own build date.

sudo bash kasm_release/install.sh -F 1.19.0-rolling-2026-05-01

Example of rolling images, static images, and dated rolling images:

  • Rolling Image: 1.19.0-rolling (updated frequently)
  • Static Image: 1.19.0 (Will not be updated)
  • Dated Rolling Image: 1.19.0-rolling-2026-05-01 (Will not be updated)

Find Available Rolling Tags​

To list the available dated rolling tags, query the Docker Hub API for one component. All core services share the same dated tags, so querying api is enough. This uses grep and sed, so no extra tooling is required:

curl -s "https://hub.docker.com/v2/repositories/kasmweb/api/tags?page_size=100" | grep -o '"name":"[^"]*"' | sed 's/"name":"//;s/"//' | grep '^1\.19\.0-rolling' | sort

To see which build your deployment currently runs, so you can compare it against the list, use Check Current Image:

sudo /opt/kasm/bin/utils/rolling_util -d

Update to a Newer Rolling Build​

To update to a newer rolling build, first determine whether your deployment is running the default -rolling tag or dated -rolling-<date> tags. Check the image tags the running Kasm services use:

sudo docker ps --format '{{.Image}}' | grep kasmweb

To the latest build, when running rolling images (the default -rolling tag): rolling tags pull the latest build on startup, so restarting Kasm updates the core services to the most recent rolling build.

sudo systemctl restart kasm

To a specific dated build (including the newest dated build): list the available tags and choose the one you want. The Rollback capability (-r <tag>) updates every service to that tag and records the current build as a rollback point; restart Kasm to apply the change.

sudo /opt/kasm/bin/utils/rolling_util -r 1.19.0-rolling-2026-07-14
sudo systemctl restart kasm

To move a deployment that is pinned to a dated tag back to the auto-updating -rolling tag, use Switch to latest.

Note

On a multi-server deployment, perform these steps on each server.

Update an Offline Deployment​

Air-gapped hosts cannot reach Docker Hub, so newer rolling images cannot be pulled directly. There are two ways to update an offline deployment, depending on your environment.

Use the offline upgrade bundles​

Follow the standard Offline Upgrade procedure in the single-server upgrade guide or the multi-server upgrade guide.

Manually transfer a specific dated build​

To move a specific dated build to an air-gapped deployment, list the available builds on an internet-connected machine, download the images for the build you want, transfer them, and load them on your Kasm servers.

On an internet-connected machine:

  1. List the available dated rolling tags. All core services share the same dates, so querying one repository (api) is enough.
curl -s "https://hub.docker.com/v2/repositories/kasmweb/api/tags?page_size=100" | grep -o '"name":"[^"]*"' | sed 's/"name":"//;s/"//' | grep '^1\.19\.0-rolling' | sort
  1. Choose a tag from the list, set it as TAG, and download all Kasm images for that build. Match the architecture of your Kasm servers with --platform, because docker pull otherwise fetches the variant for the machine you run it on.
TAG=1.19.0-rolling-2026-07-14   # the build you chose above
PLATFORM=linux/amd64            # use linux/arm64 for arm servers; must match your Kasm servers

tagged=""
for name in api agent manager proxy postgres kasm-guac rdp-gateway rdp-https-gateway; do
    docker pull --platform "$PLATFORM" "kasmweb/${name}:${TAG}"
    tagged="${tagged} kasmweb/${name}:${TAG}"
done
docker save $tagged -o "kasm-${TAG}.tar"

Transfer the resulting kasm-<tag>.tar archive to each Kasm server.

On each air-gapped Kasm server, load the images, pin every service to the tag, and restart. On a multi-server deployment, repeat this on every server.

TAG=1.19.0-rolling-2026-07-14

docker load -i "kasm-${TAG}.tar"
sudo /opt/kasm/bin/utils/rolling_util -r "$TAG"
sudo systemctl restart kasm

On restart, Kasm attempts to refresh rolling images but tolerates the failure when the server is offline, and starts from the images you loaded.

Note

Match the image architecture to your Kasm servers: an amd64 image will not run on an arm64 host, and vice versa.

Rolling Utility​

The Rolling Utility will help manage the rolling images used by Kasm. The utility contains the following capabilities:

For multi-server installation, run the rolling utility on each server.

Note

This utility will only apply to the core Kasm services.

  • API
  • Agent
  • Manager
  • Proxy
  • RDP Gateways
  • Postgres

Rollback​

This capability will roll back the image that Kasm uses to run. Since the rolling image is updated frequently, in the event that the latest rolling image is causing a problem with Kasm, you can roll back to an earlier build. Rollback has two forms, both described below: -r with no tag rolls back to the previous build by its digest, and -r <tag> sets every service to a dated tag you specify. In either case the deployment stays on the rolled-back image until you use the switch to latest feature.

sudo /opt/kasm/bin/utils/rolling_util -r

When run without a tag, the utility does not use a tag at all. It reads the previous image's digest (SHA256) from the rolling ledger and pins each service to that digest (for example, kasmweb/api@sha256:...). The ledger records the current and previous digest for every image and is refreshed automatically on each restart, so the previous digest is the build the host ran immediately before the current one. If the ledger has no previous digest for an image (for example, right after a fresh install), that image is left unchanged.

Because the ledger tracks digests, it records a new rollback point only when the running image's digest changes — that is, when a genuinely different build is pulled. Changing only the tag does not create a rollback point if both tags resolve to the same image. For example, if you pin to a dated tag and later return to -rolling while both point to the same build, a subsequent -r without a tag will not reverse that switch; it rolls back to the last build that was actually different, or does nothing. To move to a specific build in that situation, pass the tag explicitly.

You can also pass a specific tag to pin every service to that dated build, whether newer or older than the current one. See Find Available Rolling Tags to choose a tag.

sudo /opt/kasm/bin/utils/rolling_util -r 1.19.0-rolling-2026-05-01
Note

If specifying a tag, please only use tags that contain the current version of Kasm. Do not use an older version (e.g. specifying 1.18.0 tags when Kasm 1.19.0 is installed)

After using this capability, please restart Kasm.

sudo systemctl restart kasm
Rollback Limitation

If you switch to the latest rolling tag (i.e. with -l) from a dated rolling tag (i.e. installed with -F) and then attempt to rollback to the previous dated tag using -r without a specified value, verify the resulting tags in your docker compose file to ensure that the images have switched to using a SHA. It is possible that the latest rolling tag and your dated rolling tag were pointing to the same image SHA, which would cause the rolling util to leave the rolling tag on the images. If this is the case, you will need to rollback again and provide the dated rolling tag from before. E.g. -r 1.19.0-rolling-2026-05-01

Check Current Image​

This capability will output the creation date of the image currently being used by Kasm, as well as the creation date of the previously used image. This information is helpful when troubleshooting potential problems. If contacting the Kasm team for assistance, please include this information.

sudo /opt/kasm/bin/utils/rolling_util -d

Switch to latest​

During a rollback, Kasm pins the rollback version, effectively making Kasm behave as if using static images. This capability will switch Kasm back to using the latest rolling image.

sudo /opt/kasm/bin/utils/rolling_util -l

After using this capability, please restart Kasm.

sudo systemctl restart kasm

Update Rolling Tag​

This capability will update the Rolling Ledger to track the current and previous running image.

Note

The Rolling Ledger will be updated automatically after every restart. Normally, you will not need to use this capability manually.

sudo /opt/kasm/bin/utils/rolling_util -u

Clean Up Ledger​

This capability removes tracking entries from the rolling ledger for images that are no longer present on the host. It cleans up only the ledger's bookkeeping; it does not delete any Docker images or tags, so it does not reclaim disk space from old dated rolling images.

Note

Since image information can be useful in troubleshooting, please do not use this capability without being directed by the Kasm Team.

Rollback targets

A rollback with -r (no tag) restores the previous image by its digest, so old Kasm images on the host are your rollback targets. Avoid manually deleting old Kasm images (for example, with docker image prune) unless you are sure you will not need to roll back to them.

sudo /opt/kasm/bin/utils/rolling_util -c