Manage Kasm rolling images

Overview

Kasm Workspaces ships core service images as rolling tags that pull the latest build on startup, so security fixes and patches stay current without manual intervention. When a fresh rolling build introduces a regression, you need to recover quickly and prove the deployment runs a known-good version. This guide explains how to choose between rolling and static images at install time and how to use the rolling utility to roll back, inspect, and pin the image tags Kasm runs. The result is a deployment that stays patched by default yet gives you immediate change control when an update causes a problem.

Prerequisites

• Root or sudo access on every Kasm server you intend to manage.
• A working Kasm Workspaces deployment. See the single-server installation guide.
• Network access to Docker Hub to look up available image tags.

Solution approach

Rolling tags pull the latest build on startup to keep patches current. Static tags lock to a specific release for strict change control. Dated rolling tags pin a specific rolling build by date.

The following table compares the three tag types.

Tag type	Example	Update behavior
Rolling image	1.19.0-rolling	Updated frequently
Static image	1.19.0	Never updated
Dated rolling image	1.19.0-rolling-2026-05-01	Never updated

This guide progresses through the following phases:

1. Choose rolling or static images at install time.
2. Find available rolling tags.
3. Update to a newer rolling build.
4. Update an offline deployment.
5. Manage running images with the rolling utility.
6. Recover from a problematic update.

Detailed steps

Choose rolling or static images at install time

The Kasm installer uses rolling images by default. To install with static images instead, pass the -f or --use-static-images argument.

sudo bash kasm_release/install.sh -f

The installer also accepts a dated rolling image tag for the initial install. Pass the -F or --use-tag argument with the dated rolling tag you want. When you use -F or --use-tag without a value, the installer defaults to the dated rolling tag that matches its own build date.

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

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 the current image.

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

Update to a newer rolling build

First determine whether your deployment runs 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

When your deployment runs 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 move to a specific dated build, including the newest one, find the tag you want, then apply it with the roll back capability (rolling_util -r <tag>). 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 return a deployment that is pinned to a dated tag to automatic rolling updates, use switch to the latest image.

Multi-server deployments

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.

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, list the available dated rolling tags. All core services share the same dates, so querying 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

Choose a tag, then download every Kasm image for that build and save them to an archive. 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
PLATFORM=linux/amd64

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 kasm-<tag>.tar archive to each Kasm server. On each 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.

Architecture

Match the image architecture to your Kasm servers. An amd64 image will not run on an arm64 host, and the reverse.

Manage running images with the rolling utility

The rolling utility manages the rolling images Kasm runs. The utility provides the following capabilities:

• Roll back
• Check the current image
• Switch to the latest image
• Update the tracked rolling image
• Clean up the rolling ledger

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

Scope

The rolling utility applies only to the core Kasm services:

• API
• Agent
• Manager
• Proxy
• RDP gateways
• Postgres

Roll back

This capability rolls back the image Kasm runs. The rolling image updates frequently, so when the latest build causes a problem, you can roll back to the image immediately before the current one. The utility switches the image tag and holds it on the previous tag until you switch to the latest image.

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

You can also specify a tag version to use during rollback. This helps when you want an earlier, specific version of the image.

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

To find an available version, visit Docker Hub and search for any Kasm component, such as api. Docker Hub lists all available tags.

Match the installed version

When you specify a tag, use only tags that match the installed version of Kasm. Do not use an older version, such as a 1.18.0 tag while Kasm 1.19.0 is installed.

After you roll back, restart Kasm.

sudo systemctl restart kasm

Rollback limitation

When you switch to the latest rolling tag with -l from a dated rolling tag installed with -F, then roll back to the previous dated tag with -r and no value, verify the resulting tags in your Docker Compose file to confirm the images switched to using a SHA. The latest rolling tag and your dated rolling tag may point to the same image SHA, which causes the rolling utility to leave the rolling tag on the images. When this happens, roll back again and provide the dated rolling tag from before, such as -r 1.19.0-rolling-2026-05-01.

Check the current image

This capability outputs the creation date of the image Kasm currently runs and the creation date of the previously used image. This information helps when you troubleshoot a problem. Include it when you contact the Kasm team for assistance.

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

Switch to the latest image

During a rollback, Kasm pins the rollback version and behaves as if it uses static images. This capability switches Kasm back to the latest rolling image.

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

After you switch, restart Kasm.

sudo systemctl restart kasm

Update the tracked rolling image

This capability updates the rolling ledger to track the current and previous running image.

Automatic updates

The rolling ledger updates automatically after every restart. You normally do not need to run this capability manually.

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

Clean up the rolling ledger

This capability removes information about unused images from the rolling ledger.

Run only when directed

Image information helps with troubleshooting. Do not run this capability unless the Kasm team directs you to.

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

Recover from a problematic update

When a rolling update causes a problem, follow these steps to recover and confirm a known-good build.

1. Roll back to the previous image with sudo /opt/kasm/bin/utils/rolling_util -r.
2. Restart Kasm with sudo systemctl restart kasm.
3. Confirm the running image date with sudo /opt/kasm/bin/utils/rolling_util -d.
4. When the rollback resolves the issue, keep the pinned tag until a fixed rolling build is available.
5. To return to automatic updates, switch to the latest image with sudo /opt/kasm/bin/utils/rolling_util -l, then restart Kasm.

Common troubleshooting steps

• The rollback leaves a rolling tag on the images. The latest rolling tag and your dated rolling tag may share the same image SHA. Roll back again and provide the dated rolling tag explicitly, such as -r 1.19.0-rolling-2026-05-01.
• A specified tag fails or pulls the wrong build. Confirm the tag matches the installed Kasm version, and verify the tag exists on Docker Hub for the target component.
• Changes do not take effect. Restart Kasm with sudo systemctl restart kasm after a rollback or a switch to the latest image.
• A multi-server deployment runs mismatched images. Run the rolling utility on each server, because the utility manages images per server.