VPS Tutorials
Kasm Workspaces on a VPS (2026): browser isolation, HTTPS and backups
Install Kasm Workspaces 1.17.0 on Ubuntu with verified artifacts and Caddy HTTPS. Configure Zone, MFA, group policies and disposable browsers, then test backups, recovery and upgrades.

Kasm Workspaces lets you open a disposable browser or Linux desktop inside your browser. Applications run remotely in on-demand containers, reducing exposure of your local computer to unfamiliar sites and downloads. Sessions can be destroyed when finished. This reduces local risk, but containers still share the server kernel and do not guarantee safety against every exploit; protect the Kasm host and limit workspace network access.
This full guide uses Kasm Workspaces 1.17.0 on Ubuntu 24.04, with a single-server installation, Caddy HTTPS, browser isolation, users and policies, resource allocation, monitoring, database recovery and upgrades. The pinned release is a reproducible historical example, not a claim that it is the latest or suitable without checking security notices. Prefer a dedicated VPS because the installer manages several Docker services.
- Inspect unfamiliar links without downloading directly to your local computer.
- Provide temporary staff with a controlled browser or Linux desktop.
- Create disposable development, training or support environments.
- Connect to existing RDP, VNC or SSH servers through a browser.
- Control clipboard, file transfer, audio and session duration.
- Assign images and resources by group.
For fixed remote-server connections, Apache Guacamole may be lighter. Kasm adds on-demand disposable containers; full Windows VMs, kernel-separated isolation or GPU virtualization need an appropriate virtualization platform.
Review the edition license before business use. The EULA packaged with 1.17.0 restricts Community Edition usage and excludes revenue-generating business activities. Team, customer-support or training examples do not imply free commercial permission. Select the suitable licensed edition, verify its concurrent-session limits and confirm the identity/policy features you need. The installer option accepting the EULA should be used only after reviewing the applicable terms.
The official minimum is 2 CPU cores, 4 GB RAM and 50 GB SSD. Version 1.17.0 supports Ubuntu 22.04/24.04 and Debian 11/12, among other listed systems, and does not recommend LXC or WSL/WSL2.
Default workspaces can request 2 cores and 2768 MB per session. A 4 GB server therefore suits a small administrator test rather than several standard users.
| Use | Suggested starting VPS | Approximate test target |
|---|---|---|
| Personal browser isolation | 4 vCPU, 8 GB RAM, 80 GB NVMe | 1–2 standard sessions after sizing |
| Small team, browser/desktop | 8 vCPU, 16 GB RAM, 160 GB NVMe | 4–6 light sessions with tuned allocations and suitable licensing |
| Training or remote work at scale | Load-test, then split web, database and agents | Size peak concurrency |
Concurrent active sessions matter more than registered users. Resolution, audio, video, tabs and images affect consumption. The source illustrates a very small profile of 0.5 core, 768 MB, 1024×768 and no audio, and a more comfortable starting profile around 1.5 cores/2 GB. Treat these as workload-dependent examples, not guaranteed performance or current defaults. The default 2-core reservation will not fit six sessions on an 8-core agent. CPU allocation can use shares or limits; verify the configured method rather than assuming the Cores value is always a hard cap.
See the VPS sizing guide when choosing resources. Choose a region near users because interactive sessions are latency-sensitive.
The source diagram routes a user's browser through Caddy to Kasm Proxy, then the API, Manager, PostgreSQL and Agent, which creates workspace containers:
用户浏览器
|
v
Caddy :443 ---- 自动 HTTPS
|
v
Kasm Proxy :8443 ---- API / Manager / PostgreSQL / Agent
|
v
按需创建 Workspace 容器
Kasm normally uses 443. Install on 8443 so Caddy owns public HTTPS. Allow:
- 22/TCP for SSH restricted to administration addresses.
- 80/TCP for certificate validation and HTTP redirects.
- 443/TCP for the Kasm web entry.
This setup does not use a native RDP-client gateway, so it does not require 3389. Keep 8443 private; a custom listening port is not automatically a loopback binding.
Point kasm.example.com to the VPS using a correct A record and working IPv6 only if using AAAA. Inspect the host:
cat /etc/os-release
uname -m
free -h
df -h /var/lib/docker 2>/dev/null || df -h /
sudo ss -lntup | grep -E ':(80|443|8443)\b' || true
The installer installs or uses Docker and creates services under /opt/kasm. Check collisions with existing Nginx, Traefik, databases, ports, networks and disk use; a separate host is easier to maintain.
Update Ubuntu and install tools/Caddy:
sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl caddy
sudo systemctl enable --now caddy
Keep an SSH session and provider console available before applying UFW:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose
Docker publications can bypass ordinary UFW input handling. Explicitly deny public 8443 in the provider firewall, verify the actual Kasm bindings and test from an external host. For stronger restriction, apply a supported private binding or Docker forwarding policy for this deployment.
The source's installer URL and SHA-256 match the official 1.17.0 installation documentation and the downloaded package:
cd /tmp
curl -fLO \
https://kasm-static-content.s3.amazonaws.com/kasm_release_1.17.0.7f020d.tar.gz
echo \
'22a293ea52b2adb7f3f72a2de8e9be799f443b9da040e066df403478da77f62d kasm_release_1.17.0.7f020d.tar.gz' \
| sha256sum -c -
tar -xzf kasm_release_1.17.0.7f020d.tar.gz
Proceed only after OK. Use a clean temporary directory if previous extraction files exist; do not mix releases. ARM64/offline artifacts have their own hashes, and not every workspace image supports ARM64. Check the image matrix before purchasing an ARM server.
Check existing swap:
swapon --show
free -h
If absent, the example asks the installer to create 8 GB swap and use port 8443:
cd /tmp
sudo bash kasm_release/install.sh \
--accept-eula \
--swap-size 8192 \
-L 8443
Remove --swap-size 8192 when adequate swap already exists. The option is in megabytes; swap does not replace RAM for active sessions. Allow space for service/workspace images beyond the 50 GB floor. On slow downloads, inspect kasm_install_时间戳.log rather than repeatedly reinstalling.
Save generated credentials for [email protected] and [email protected] immediately in a password manager. Do not publish terminal screenshots or embed passwords in commands.
Check services and health:
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
curl -kfsS https://127.0.0.1:8443/api/__healthcheck
sudo /opt/kasm/bin/status
Expect {"ok": true}. -k is only for local checking of the upstream self-signed certificate.
Edit /etc/caddy/Caddyfile with your real hostname:
kasm.example.com {
encode zstd gzip
reverse_proxy https://127.0.0.1:8443 {
transport http {
tls_insecure_skip_verify
}
header_up Host {host}
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Proto https
header_up X-Forwarded-Port 443
flush_interval -1
}
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
Referrer-Policy "same-origin"
}
}
tls_insecure_skip_verify skips verification only for Caddy's same-host upstream. Browsers still validate public HTTPS. For a remote upstream, configure trusted TLS rather than copying this exception. For stricter local verification, trust the internal CA and use a matching certificate name. Consider the effect of HSTS includeSubDomains before enabling it.
Validate and load:
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsS https://kasm.example.com/api/__healthcheck
Caddy supports WebSockets automatically. flush_interval -1 disables response buffering for interactive streams. See the Caddy guide for multiple domains and certificate diagnosis.
A working login does not prove workspace connectivity. Open:
Infrastructure -> Zones -> default
Set Upstream Auth Address to proxy and Proxy Port to 0. End old test sessions and create new ones; Zone changes apply to new sessions, not existing connections.
If later enabling native RDP Client Workspaces behind the proxy, review Restrict RDP Client IP Address. The official guide describes disabling that setting for this topology to avoid Invalid Request. Wrong client IP; compensate with suitable gateway access controls and review the changed IP-check behavior.
- Change the generated password of
[email protected]. - Disable or delete
[email protected]. - Enable supported TOTP/WebAuthn MFA for administrators.
- Create a daily administration account; do not use it for ordinary browsing.
- Consider reducing allowed failed logins from 5 to 3 after evaluating lockout and recovery needs.
- Shorten idle and maximum session lifetimes.
- Confirm anonymous access is disabled.
Kasm supports local authentication and LDAP/SAML/OIDC options subject to version/edition. Use a suitable identity provider for teams, while keeping an MFA-protected local emergency administrator and offline recovery credentials.
Create a group such as Browser-Isolation under Access Management → Groups. Group names and priorities must be unique. Lower-priority-number settings take precedence when the same single-valued policy appears in several groups; settings such as volume_mapping combine across groups. Review effective permissions, not only one group.
Set a restrictive All Users baseline:
- Disable file uploads/downloads.
- Disable bidirectional clipboard.
- Disable microphone and camera.
- Limit idle and maximum duration.
- Limit simultaneous sessions.
- Avoid automatically granting newly imported workspaces.
Open specific permissions only for groups needing them. Disable automatic assignment of new Workspaces to All Users, and explicitly assign images to groups so newly imported powerful images are not visible to everyone.
In Workspaces → Registry, add the official registry and select only needed images. Each desktop can occupy several gigabytes, with old and new layers overlapping during updates.
A starting selection could include:
- Chromium or Firefox for unfamiliar sites and temporary logins.
- Ubuntu Desktop for file management and terminals.
- Remmina for approved RDP, VNC and SSH connections.
- VS Code for temporary development and training.
Start with measured conservative allocations such as 1.5 CPU and 2 GB per light workspace, then tune. Video meetings and simple pages differ greatly; do not apply one limit to every image.
Verify:
- Users see only workspaces assigned to their groups.
- A browser session reaches an approved test site.
- Clipboard and file-transfer policies take effect.
- Ending a session removes the corresponding temporary container.
- A new disposable session does not unexpectedly retain downloads or cookies.
For unfamiliar links, prefer disposable sessions without host-directory mappings or persistent profiles. Persisting data changes the isolation boundary:
- Malicious extensions, cookies and downloads may survive sessions.
- Persistent directories need backups, quotas and malware handling.
- User removal and data deletion need a defined process.
- Different users must not share one writable profile directory.
For one-time browsing, destruction is usually preferable. When persistence is necessary, give each user a separate path and test restoration. Remote browsing does not protect secrets deliberately entered into an untrusted website.
Remote graphics consume CPU and bandwidth. On a small host, try:
- Low/Medium video quality.
- Maximum resolution 1280×720.
- Audio disabled when unnecessary.
- Light-browser allocations around 0.5–1 CPU and 1–1.5 GB, tested for your pages.
- One session per user.
- Idle destruction.
- Pre-pulling only needed images.
Observe peak use through docker stats:
sudo docker stats
sudo docker system df
free -h
df -h /var/lib/docker
Test the expected simultaneous real sessions for 20–30 minutes, including scrolling, video and permitted clipboard use. Sustained CPU above roughly 80%, growing swap or repeated reconnections calls for lower concurrency or more resources. A login-page test is insufficient.
Images and layers normally reside in /var/lib/docker. Free space elsewhere does not fix a full Docker data filesystem. Check Docker's actual data root if customized.
Monitor:
- Root and Docker filesystem usage.
- Inode usage.
- Core-container status and restart counts.
/api/__healthcheckavailability.- CPU, RAM, swap and network traffic.
- PostgreSQL backup results.
Quick inspection:
sudo /opt/kasm/bin/status
curl -kfsS https://127.0.0.1:8443/api/__healthcheck
sudo docker ps --filter 'name=kasm_' \
--format 'table {{.Names}}\t{{.Status}}\t{{.RunningFor}}'
sudo docker system df
Integrate health, disk and restart monitoring with Zabbix if already used across servers.
PostgreSQL holds users, groups, workspace definitions and settings. The official online dump example is:
sudo mkdir -p /var/backups/kasm
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
sudo docker exec kasm_db \
pg_dump -U kasmapp -F t kasm \
| sudo tee "/var/backups/kasm/kasm-db-$STAMP.tar" >/dev/null
The source also archives configuration:
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
sudo tar -czf "/var/backups/kasm/kasm-config-$STAMP.tar.gz" \
/opt/kasm/current/conf \
/opt/kasm/current/docker
sudo sha256sum /var/backups/kasm/kasm-* \
| sudo tee "/var/backups/kasm/SHA256SUMS-$STAMP" >/dev/null
Use one private backup directory and restrictive permissions. Separate timestamps and absolute-path checksum records in the original do not establish a coordinated recovery set. End active sessions and freeze administrative changes before pairing the dump, configuration and persistent user files. The following version preserves one identity, version directory, Caddy configuration and relative checksums:
sudo bash <<'BACKUP'
set -Eeuo pipefail
umask 077
install -d -m 0700 /var/backups/kasm
backup_dir=$(mktemp -d "/var/backups/kasm/$(date -u +%Y%m%dT%H%M%SZ)-XXXXXX")
kasm_version_dir=$(readlink -f /opt/kasm/current)
test -d "$kasm_version_dir/conf"
test -d "$kasm_version_dir/docker"
docker exec kasm_db pg_dump -U kasmapp -Fc kasm > "$backup_dir/kasm.dump"
tar -czf "$backup_dir/configuration.tar.gz" -C "$kasm_version_dir" conf docker
printf '%s\n' "$kasm_version_dir" > "$backup_dir/version-directory.txt"
cp -p /etc/caddy/Caddyfile "$backup_dir/Caddyfile"
mapfile -t kasm_ids < <(docker ps -aq --filter name=kasm_)
test "${#kasm_ids[@]}" -gt 0
docker inspect --format '{{.Name}} {{.Config.Image}} {{.Image}}' "${kasm_ids[@]}" > "$backup_dir/images.txt"
docker inspect --format '{{.Name}} {{json .Mounts}}' "${kasm_ids[@]}" > "$backup_dir/mounts.txt"
(cd "$backup_dir" && sha256sum kasm.dump configuration.tar.gz version-directory.txt Caddyfile images.txt mounts.txt > SHA256SUMS && sha256sum -c SHA256SUMS)
printf 'Backup directory: %s\n' "$backup_dir"
BACKUP
It backs up the database and shown configuration, not all files. Separately include Persistent Profiles, Volume Mappings, shared paths, NFS, object storage and any external certificate/key material. Keep file ownership and paths consistent with the restore. A transactional database dump does not make actively changing user files consistent automatically.
Encrypt and copy the complete recovery set offsite. Sample a restore at least monthly. See the VPS recovery-drill guide for retention and verification.
The official pg_restore -c restore overwrites existing objects. The source example is:
sudo docker cp kasm-db-backup.tar kasm_db:/tmp/backup.tar
sudo docker exec kasm_db \
pg_restore -d kasm /tmp/backup.tar -c -U kasmapp
Use an isolated test destination initially. Install the matching Kasm version, reconcile its configuration, database credentials and hostname references, restore the corresponding external files and keep users/workspace writers stopped while PostgreSQL is running. The reviewed database phase is:
# Run only on the isolated recovery destination with the matching Kasm version.
sudo bash <<'RESTORE'
set -Eeuo pipefail
backup_dir=/var/backups/kasm/RESTORE_POINT
(cd "$backup_dir" && sha256sum -c SHA256SUMS)
/opt/kasm/bin/stop
docker start kasm_db
until docker exec kasm_db pg_isready -U kasmapp -d kasm >/dev/null; do sleep 2; done
docker cp "$backup_dir/kasm.dump" kasm_db:/tmp/kasm-restore.dump
docker exec kasm_db pg_restore --exit-on-error -c -U kasmapp -d kasm /tmp/kasm-restore.dump
docker exec kasm_db rm -f /tmp/kasm-restore.dump
/opt/kasm/bin/start
RESTORE
Replace RESTORE_POINT with the verified backup directory. Do not continue after an error. A production restore requires a scheduled outage and a reviewed recovery plan because it overwrites data. Verify login, groups, workspace assignments, new session creation, enforced policies and readable persistent files, not just Running containers.
Review the target release's OS, Docker, image and configuration migration requirements. Version 1.17.0 changed several configuration paths; do not reuse older locations blindly.
- Announce maintenance to users.
- End all active workspaces.
- Save database, configuration, persistent files and a VPS snapshot.
- Ensure at least the source's 50 GB free-space target on the Docker filesystem and check the target release's actual requirement.
- Download the target and verify its SHA-256.
- Use the target's official
upgrade.sh. - Verify login, Zone, sessions, policies and backups.
- Update workspace images through the Registry afterward.
Preserve port 8443 during an upgrade:
cd /tmp
curl -fLO \
https://kasm-static-content.s3.amazonaws.com/kasm_release_1.17.0.7f020d.tar.gz
echo \
'22a293ea52b2adb7f3f72a2de8e9be799f443b9da040e066df403478da77f62d kasm_release_1.17.0.7f020d.tar.gz' \
| sha256sum -c -
tar -xzf kasm_release_1.17.0.7f020d.tar.gz
sudo bash kasm_release/upgrade.sh --proxy-port 8443
This example upgrades a supported older installation to 1.17.0; do not rerun it on a server already at 1.17.0. Follow the actual target version's guide. Repeating install.sh is not an upgrade. After database/config migrations, rollback should restore the matching pre-upgrade data and software rather than merely changing images.
curl -kfsS https://127.0.0.1:8443/api/__healthcheck
sudo systemctl status caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager
curl -fsS https://kasm.example.com/api/__healthcheck
If local 8443 fails, inspect Kasm. If local works but the domain does not, inspect Caddy, DNS and provider rules.
Check Zone Upstream Auth Address proxy, Proxy Port 0, and create a fresh session. Verify Caddy reaches https://127.0.0.1:8443 and any preceding CDN/proxy allows WebSockets.
free -h
swapon --show
sudo docker stats --no-stream
sudo docker system df
Lower workspace allocations only when genuinely appropriate for measured workload. A full or swapping host needs fewer sessions or more capacity, not continually reduced minimums.
Remove unused workspace definitions/images through administration, then inspect:
df -h /var/lib/docker
df -i /var/lib/docker
sudo docker system df -v
Do not indiscriminately run docker system prune -a; it can remove planned images, force later downloads or affect other projects.
cd /tmp
ls -lh kasm_install_*.log
tail -n 200 kasm_install_*.log
sudo docker info
df -h /
Check free space, supported Docker version, 443/8443 conflicts and registry connectivity. Diagnose logs before repeating the installer.
- Supported host OS on an appropriate VM/bare-metal platform, not LXC.
- Edition/license, architecture and peak session capacity reviewed.
- Installer SHA-256 verified.
- Only restricted SSH, HTTP and HTTPS public; 8443 denied externally.
- Caddy HTTPS and health checks working.
- Zone Upstream Auth Address=proxy and Proxy Port=0.
- Default ordinary user disabled; administrator MFA enabled.
- Restrictive All Users baseline and explicit workspace assignments.
- Clipboard, files and disposable-session destruction tested.
- Docker filesystem, swap, health and restarts monitored.
- Database, configuration and persistent directories backed up offsite.
- Recovery can create a real workspace.
- Upgrade ends active sessions and preserves the 8443 setting.
Installation and a light test may work, but a default session requests 2 cores/2768 MB. Start around 4 cores/8 GB for ongoing personal use, then measure concurrency.
Guacamole exposes existing RDP/VNC/SSH hosts through a browser. Kasm additionally creates disposable browser/Linux containers. Choose according to fixed connections versus temporary workspaces.
The vendor does not recommend it. Nested Docker networking, permissions and kernel capabilities can cause problems. Prefer a suitable VM or bare metal.
Set Zone proxy and 0, terminate the old session and create another. Check WebSocket proxying.
Only temporary container data is discarded. Profiles, mapped/shared directories and external storage persist; effective workspace/group policy determines the behavior.
It contains definitions and settings, not all profile, mapped, NFS or object-storage files. Back them up separately and verify them in the same recovery drill.