How to Add a Custom Docker Image to Kasm Workspaces (End-to-End)

Overview

This guide walks through the complete path for adding a custom container image to Kasm Workspaces:

• Create a Dockerfile
• Build and test the image locally
• Push it to a container registry
• Add it in Kasm as a new workspace
• Verify it appears and launches correctly

By the end, the image will be visible in the Kasm Workspaces catalog and ready for users.

Prerequisites

• A running Kasm Workspaces deployment
• Admin access to Kasm
• Docker installed on your build machine
• A container registry you can push to:
  • Docker Hub
  • GitHub Container Registry (GHCR)
  • Private registry (optional)

If your registry is private, ensure Kasm can authenticate to pull images.

1. Create the Dockerfile

Start with a Kasm-compatible base image. The easiest approach is to inherit from an official Kasm image and add only what you need.

FROM kasmweb/core-ubuntu-jammy:1.16.0

USER root

# Install tools needed in your workspace
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      curl \
      git \
      jq \
      vim && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

# Optional: copy internal scripts/config
# COPY scripts/ /opt/custom-scripts/

USER 1000
WORKDIR /home/kasm-user

Notes:

• Keep images lean to improve launch time.
• Prefer pinned versions for reproducibility.
• Always switch back to non-root unless you explicitly need root runtime.

2. Build the Image

docker build -t your-registry/kasm-custom-ubuntu:1.0.0 .

Run a quick local test:

docker run --rm -it your-registry/kasm-custom-ubuntu:1.0.0 bash

Inside the container, validate your expected tools/files are present.

3. Push to a Registry

Authenticate to your registry, then push:

docker push your-registry/kasm-custom-ubuntu:1.0.0

Examples:

# Docker Hub
docker tag kasm-custom-ubuntu:1.0.0 docker.io/<username>/kasm-custom-ubuntu:1.0.0
docker push docker.io/<username>/kasm-custom-ubuntu:1.0.0

# GHCR
docker tag kasm-custom-ubuntu:1.0.0 ghcr.io/<org>/kasm-custom-ubuntu:1.0.0
docker push ghcr.io/<org>/kasm-custom-ubuntu:1.0.0

Use immutable tags (1.0.0, 1.0.1, etc.) instead of only latest.

4. Add the Image in Kasm Workspaces

1. Log in as Kasm admin.
2. Go to Workspaces -> Workspaces.
3. Click Add Workspace (or duplicate an existing workspace for faster setup).
4. Fill in:
   • Name: Friendly name shown to users
   • Description: Short purpose
   • Docker Image: Full image reference, e.g. ghcr.io/acme/kasm-custom-ubuntu:1.0.0
   • Cores / Memory / GPU: Resource profile
   • Categories and Thumbnail: Optional but recommended
5. Save the workspace.

If your image is in a private registry, configure registry credentials in Kasm before testing launches.

5. Verify It Appears and Launches

After saving:

• Open the user workspace catalog
• Confirm the new workspace card is visible
• Launch a session
• Validate:
  • Container starts cleanly
  • Desktop/app loads
  • Custom tools are installed
  • No permission/runtime errors

Troubleshooting

Common issues and fixes:

• Image not visible in catalog:
  • Check workspace Enabled status and user/group entitlements.
• Launch fails with image pull error:
  • Verify image name/tag and registry auth.
• Session starts but custom tools missing:
  • Confirm you pushed the correct tag and updated Kasm to that exact tag.
• Slow startup:
  • Reduce image size and remove unnecessary packages.

Recommended Workflow for Updates

For future changes, follow this cycle:

1. Update Dockerfile
2. Build + test locally
3. Push new version tag (e.g. 1.0.1)
4. Update workspace image tag in Kasm
5. Re-test with a fresh session

This keeps deployments predictable and makes rollbacks easy.

Final Thoughts

Once this pattern is in place, adding new team-specific environments to Kasm becomes fast and repeatable. Build small, version clearly, and treat each workspace image like production infrastructure.