Gino George John

Kasm Workspaces on Docker in a Proxmox LXC Container

A Complete Guide to Installing Kasm Workspaces on Docker in a Proxmox LXC Container

This guide provides a start-to-finish walkthrough for installing Kasm Workspaces. We’ll cover the entire process, from preparing the Proxmox host to troubleshooting the most common errors that can pop up, especially when using an LXC container.

What is Kasm Workspaces?

Kasm Workspaces is a powerful open-source platform that streams containerized desktops and applications directly to your web browser. It’s a fantastic tool for creating secure, isolated, and on-demand work environments.

Step 1: Prepare the Proxmox Host (The LXC tun Fix)

This is the most critical step for anyone using an LXC container. For security, Proxmox doesn’t allow containers to access the host’s networking devices by default. Kasm needs the /dev/net/tun device to manage its virtual network, so we must grant permission.

All commands in this step are run on the Proxmox host’s shell, not the container.

  1. Enable the tun Module on the Host:First, ensure the tun module is loaded and will load on every boot.Bashsudo modprobe tun echo tun | sudo tee /etc/modules-load.d/tun.conf
  2. Grant the LXC Container Permission:Find your container’s ID (e.g., 101, 102) from the Proxmox web UI. Then, edit its configuration file.Bash# Replace 101 with your container's ID sudo nano /etc/pve/lxc/101.conf Add these two lines to the bottom of the file:Plaintextlxc.cgroup2.devices.allow: c 10:200 rwm lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file
  3. Restart the Container:You must perform a full shutdown and start, not just a reboot.Bash# Replace 101 with your container's ID sudo pct shutdown 101 # Wait a few seconds... sudo pct start 101

Step 2: Prepare the Ubuntu Container

Now, log into your Ubuntu container’s shell to get it ready for the installation.

  1. Update System Packages:Bashsudo apt update && sudo apt upgrade -y
  2. Create a Swap File:The Kasm installer requires a swap partition to be active.Bashsudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
  3. Verify the tun Device:Confirm that Step 1 worked. This command should now succeed.Bashls /dev/net/tun If it returns No such file or directory, go back and carefully re-check Step 1.

Step 3: Install Kasm Workspaces

With the environment prepared, it’s time to run the installer.

  1. Create a Dedicated Folder:Bashmkdir ~/kasm-install cd ~/kasm-install
  2. Download the Kasm Release:Go to the Kasm Workspaces Downloads Page, right-click the download link for the .tar.gz file, and select “Copy Link Address”.Bash# Paste the link you copied inside the quotes wget "paste-the-new-link-here"
  3. Extract and Run the Installer:Bash# Extract the archive tar -xf kasm_release_*.tar.gz # Run the installation script sudo bash kasm_release/install.sh

Step 4: Troubleshooting Common Errors

If you run into trouble, it’s likely one of these common issues.

Error 1: Port Conflict

  • Error Message: Port (443) is in use. Installation cannot continue.
  • Cause: Another service (often another Docker container like Traefik or Nginx Proxy Manager) is already using the default HTTPS port 443.
  • Solution: Install Kasm on a different port using the --proxy-port flag.Bashsudo bash kasm_release/install.sh --proxy-port 8443 You will then access Kasm at https://<your-ip>:8443.

Error 2: Corrupted Download

  • Error Message: tar: This does not look like a tar archive
  • Cause: The download failed or you saved an HTML error page instead of the actual file. This is often because the direct download link expired.
  • Solution: Delete the bad file (rm kasm_release_*.tar.gz) and get a fresh download link from the official Kasm website as shown in Step 3.

Error 3: Missing tun Device

  • Error Message: error gathering device information while adding custom device "/dev/net/tun": no such file or directory
  • Cause: This happens when Kasm’s network plugin cannot find the necessary virtual networking device. For Proxmox users, this means Step 1 was missed or done incorrectly.
  • Solution: Stop, go back to Step 1, and complete it carefully. Ensure you fully shut down and start the container, not just reboot it.

Error 4: WireGuard Fails to Install

  • Message: failed to install wireguard support
  • Cause: This optional component failed because your container is missing the correct kernel headers.
  • Is it OK? Yes, this is not a critical error. Kasm will automatically fall back to a TCP-based connection. Your installation will work fine. You can optionally fix it later by installing the headers (sudo apt install linux-headers-$(uname -r)) and rebooting.

Step 5: Finalizing the Installation

  1. Save Your Credentials!After a successful installation, the script will display your admin and user credentials. This is the only time they will be shown. Copy them immediately and save them in a secure password manager.
  2. Log In:Open your web browser and navigate to your server’s IP address. Remember to add the port if you used a custom one (e.g., https://192.168.1.100:8443). You will see a security warning for the self-signed certificate—this is normal, and you can safely proceed. Log in with the admin@kasm.local account.

Congratulations! Your Kasm Workspaces instance is now up and running.

How this Result was Reached:

This guide was created by synthesizing the step-by-step troubleshooting process from our conversation with official documentation and best practices. I used the Google Search tool to consult the official Kasm Workspaces installation guide, the Proxmox VE documentation for LXC containers, and standard Linux administration guides. The result is a consolidated, real-world walkthrough that directly addresses the specific challenges of a Proxmox LXC environment, ensuring the information is accurate, fact-based, and provides a reliable path to a successful installation.

Skip to content