kasm

Custom Kasm Workspace images built from scratch
Ubuntu 24.04 + KDE Plasma + KasmVNC, with a clean layer for your own tools on top.

Why • How It Works • Contents • Get Started • Registry • License

---

Status — Active. Core image builds on every push to main via GitHub Actions and publishes to GHCR.

---

Why kasm

The official Kasm workspace images are large, opinionated, and hard to audit. This repo builds from ubuntu:24.04 directly, layering only what is needed: KDE Plasma desktop, KasmVNC, and the platform services (audio, webcam, printer, gamepad, smartcard, profile sync). Your custom tooling sits in a separate image layer on top, so rebuilding it does not require rebuilding the 4 GB base.

Benefits:

• Full provenance — every layer is built from source in your own GitHub Actions pipeline
• Clean extension point — one script (src/install/custom/install_custom.sh) and one Dockerfile (Dockerfile) are all you touch
• Fast iteration — the core image is cached; custom rebuilds are seconds, not minutes
• Self-hosted registry — a Kasm-compatible JSON registry is published to GitHub Pages so you can add the image directly in the Kasm UI

---

How It Works

The build is split into two stages so the slow core build is cached independently from your fast custom layer.

ubuntu:24.04
    |
    v  Dockerfile.core
kasm-kde-noble:core          (~4 GB, slow — built once)
    |   KDE Plasma, KasmVNC, audio, webcam, printer,
    |   gamepad, smartcard, profile sync, VirtualGL,
    |   Squid, Sysbox systemd, custom cursors & fonts
    |
    v  Dockerfile
kasm-kde-noble:latest        (your tools on top, fast)
        build-essential, git, curl, wget, vim,
        htop, jq, tree, unzip, net-tools, dnsutils, ...

The core image uses a two-stage Docker build internally (base_layer then scratch) to produce a clean filesystem with no build-time cruft.

CI runs both builds sequentially (build-core then build-custom) via GitHub Actions and pushes both to GHCR on every merge to main. Pull requests build the core image only (no push).

---

Image Contents

Core image — kasm-kde-noble:core

Component	Details
Base OS	Ubuntu 24.04 (Noble)
Desktop	KDE Plasma 5 (START_DE=kde5)
VNC server	KasmVNC (/usr/share/kasmvnc)
noVNC port	6901 (HTTPS)
VNC port	5901
Audio port	4901
Display	:1, 1280x720, 24-bit colour, max 24 fps
Audio	PulseAudio (START_PULSEAUDIO=1)
GPU	NVIDIA EGL acceleration supported
Extra services	Webcam, gamepad, printer (CUPS), smartcard (pcscd), Squid proxy, profile sync, upload server
User	kasm-user (UID/GID 1000)
Timezone	Etc/UTC (override with TZ)

Custom image — kasm-kde-noble:latest

Inherits everything from core, and adds:

Package	Purpose
build-essential	C/C++ toolchain
git	Version control
curl, wget	HTTP clients
vim	Editor
htop	Process monitor
jq	JSON processing
tree	Directory listing
unzip, zip	Archive tools
net-tools, iputils-ping, dnsutils	Network diagnostics
ca-certificates, gnupg, software-properties-common	Package management

---

Getting Started

Prerequisites

• Docker with Buildx
• Git (with submodule support — the upstream/ directory is a submodule)

git clone --recurse-submodules https://github.com/wan0net/kasm.git
cd kasm

Build

# Build the core image (Ubuntu 24.04 + KDE + KasmVNC) — slow, do once
./build.sh core

# Build the custom overlay (your tools on top) — fast
./build.sh custom

# Build both in sequence
./build.sh all

Run

# Run the custom image
./build.sh run

# Run the core image only (no custom tools)
./build.sh run-core

# Open a shell in the running container
./build.sh shell

Or with Docker Compose:

docker compose up

Access the desktop at https://localhost:6901

Field	Value
URL	https://localhost:6901
User	kasm_user
Password	password (override with VNC_PW env var)

Extend

Add your own tools to src/install/custom/install_custom.sh. The script runs as root inside the container during docker build. The Dockerfile copies it into the image and executes it automatically.

# src/install/custom/install_custom.sh
apt-get install -y --no-install-recommends \
    python3 python3-pip python3-venv \
    nodejs npm

Then rebuild the custom image:

./build.sh custom

If you need to modify the base stack (KDE config, KasmVNC settings, platform services), edit Dockerfile.core and rebuild with ./build.sh all.

Clean up

./build.sh clean

---

Registry

A Kasm-compatible workspace registry is published to GitHub Pages at https://wan0.net/kasm/. The registry is updated automatically when files under registry/ change on main.

To add this registry in the Kasm UI: Admin > Workspaces > Registry > Add Registry and enter:

https://wan0.net/kasm/

The registry currently lists one workspace:

Name	Image	Architectures	Kasm compatibility
Ubuntu Noble KDE	ghcr.io/wan0net/kasm-kde-noble:latest	amd64	1.14.x – 1.18.x

---

License

MIT. See LICENSE for details.