Skip to main content
Version: Developer

Multi Server Installation

In this example, the Kasm services are installed on different servers within the environment. Depending on the desired use case, these servers can be put in separate network enclaves according to your environment and typical security best practices.

Please read through the entire process before getting started.

Troubleshooting info can be found on the Troubleshooting Page

Issues can be reported on the Kasm Workspaces Issues Page

Architecture Roles​

The following outlines the Role Service in this architecture. The ports and protocols required for communication are listed to allow for firewalls or filtering devices in your environment

Web App Server(s)

This is the landing point for end users. If end-users access this server from the internet this may be put in a DMZ enclave. This Server includes the following services:

  • Ports / Protocols
    • HTTPS (443)

Database Server

The database server must be accessible by API and Management Services. This Server includes the following services:

  • Ports / Protocols
    • POSTGRESQL (5432)

Agent Server(s)

Agents are where end-user sessions are created. Depending on the desired architecture these may be placed in various locations. The agent must be accessible by the Management and Web App Servers. This server includes the following services:

  • Agent Service (kasm_agent)
  • Proxy (kasm_proxy)
  • OTel Collector (kasm_otel_collector)
  • Ports / Protocols
    • HTTPS (443)

ClickHouse (Observability Database) Server

The ClickHouse observability database stores all telemetry (logs, traces, and metrics). In a multi-server deployment it runs on its own dedicated server and must be accessible by the Web App Server, which reads telemetry for the UI reports and log viewer and forwards telemetry to it through the OTel Collector. This is a required role for a multi-server deployment, exactly like the Database Server. ClickHouse is bundled on the node only in a single-server (all) installation. This server includes the following services:

  • ClickHouse Service (kasm_clickhouse)
  • Ports / Protocols
    • HTTPS (8443) — secure ClickHouse HTTP interface, used by the Kasm API for UI reports and the log viewer
    • Secure Native TCP (9440) — secure ClickHouse native interface, used by the OTel Collector to write telemetry
Note

This role does not run an OTel Collector and does not forward telemetry on its own; it is a storage endpoint only. Both ports are published to the network over TLS so that the app/all node can reach it. For details, see the Observability configuration reference page.

Connection Proxy(s)

Connection proxies are used to broker web native RDP/VNC/SSH and RDP thick client sessions to fixed or autoscaled servers. If this functionality is not needed, this role does not need to be installed. Connection proxies need to be accessible from the WebApp servers and to the destination RDP/VNC/SSH servers. If RDP thick client access is desired then the Connection Proxy role must be internet accessible. This server includes the following services:

  • Guac Service (kasm_guac)
  • RDP Gateway Service (kasm_rdp_gateway)
  • proxy (kasm_proxy)
  • OTel Collector (kasm_otel_collector)
  • Ports / Protocols
    • HTTPS (443)
    • RDP (3389)

Multi Server Install

Multi Server Install

Ports and Protocols​

Note

The ports listed below are defaults. The listening port for agents and web app servers can be customized during installation using the -L flag (e.g., install.sh --role agent -L 5173). If you change default ports, ensure all firewall rules and autoscale configurations are updated accordingly.

SourceDestinationPortNotes
End UserWeb App Server443Web Application / UI / API
End UserConnection Proxy (rdp-gateway)3389RDP Connection
Web App ServerDatabase Server5432Database Access (PostgreSQL)
Web App ServerAgent Server443Agent Instructions
Web App ServerConnection Proxy (Guac)443Proxied RDP Connections to VMs/Hardware
Web App ServerVM/Hardware (KasmVNC)8443Proxied KasmVNC Connections to VMs/Hardware
Agent ServerManagement Server443Check-in, Request Images, Request Authentication
Connection Proxy (Guac)VM/Hardware RDP Systems3389Converts RDP to Web native rendering via Guac
Connection Proxy (Guac)VM/Hardware VNC Systems5900Converts VNC to Web native rendering via Guac
Connection Proxy (Guac)VM/Hardware SSH Systems22Converts SSH to Web native rendering via Guac
Connection Proxy (Guac)Web App Server443RDP Connection Authorization and Status Checks
Connection Proxy (rdp-gateway)VM/Hardware RDP Systems3389RDP Connection
Remote nodes (agent, db, guac, proxy)App/All node4317Telemetry signals including logs, traces, and metrics using OTLP/gRPC protocol
App nodeClickHouse node8443App queries for logs and telemetry, to populate UI reports
App nodeClickHouse node9440Telemetry signals forwarded by the App node's collector

System Requirements​

Please review the System Requirements before beginning.

tip

Kasm provides a Sizing and Deployment Guide to aid in determining hardware specifications for large scale deployments.

Installation Guide​

Follow these steps to setup Kasm on separate servers.

Install Database Server Role​

Note

The Database can be configured as a standalone database such as an Amazon RDS instance or an existing Postgres instance, instead of the container provided by Kasm Technologies. For more information, see Standalone Remote Database.

The following steps will install the database service on the Database Server.

  • Download the latest version of Kasm Workspaces to /tmp
  • Extract the package and execute the installation. Please note the default login credentials produced during the install.
Install Files
ContentsURLSHA256
Installer Bundlehttps://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0.tar.gz7b801cb0579a7867df46b6da873fe8dd631db07d4c05349e5bd1aea27130c37d
ContentsURLSHA256
Serviceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_amd64_1.19.0.tar.gzc8697a7d6db6d6c2cd685cf431977e79bb4adfa35d91d6fab455e70f4441e46d
Workspaceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_amd64_1.19.0.tar.gz2338ed95653cf37b41c32c4202c38b507fd94a745dc81a303402e20f292486da
Network Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_network_plugin_images_amd64_1.5.tar.gzbd13ce71737cebf2e7559c01c2dbff657a52505c771fce450a32bed36ef3056d
Logging Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_logging_plugin_images_amd64_1.1.tar.gzfe5d1d6d1acd42ea89e15e375d0d6719f9d6cbf1f9c6943c4fda901a3d529135
ContentsURLSHA256
Serviceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_arm64_1.19.0.tar.gzf7975cecf89fc5b1e3886c09178047e7d6f092344ab15f9babfdeaeeb8d01801
Workspaceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_arm64_1.19.0.tar.gz5ee92ebac22c7399694c9a7eef4d0baddc98c315c2d78848fa3a757d66bcd2c4
Network Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_network_plugin_images_arm64_1.5.tar.gz59d23f6765f26be86a00fed31b38873d36f9b7b7ecf608a2efb270d969621ae6
Logging Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_logging_plugin_images_arm64_1.1.tar.gz1d720994c141fe9743b566ea2affeee77759e272ad777d0257ed6a089dd3b802
Note

If you have an activation key it can be passed to the installation script and activation will be completed on your behalf as part of the install. Create a file for the activation key e.g. activation_key.txt and paste in the activation key you received in your confirmation email. When running the install.sh use the parameter -a or --activation-key-file so your command might look something like this sudo bash kasm_release/install.sh -a activation_key.txt. This will not work with an offline air-gapped install, as Kasm Workspaces must contact an activation server to complete licensing your installation. In a multi server install this option only applies to the database role.

cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/install.sh --role db --database-user [DATABASE_USERNAME] --database-name [DATABASE_NAME]
note

Starting in 1.19.0, the default installation uses rolling images to deliver ongoing security fixes and updates. For static images with manual update control, pass the -f or --use-static-images argument during the installation or upgrade process.

sudo bash kasm_release/install.sh -f

or

sudo bash kasm_release/upgrade.sh -f

Refer to Rolling Image Management for more information about rolling images.

Note

The DATABASE_USERNAME and DATABASE_NAME are optional and only required if not using the default kasm/kasmapp settings on an Installation 1.13.0 or newer.

Install ClickHouse Role​

Note

The ClickHouse telemetry database can be configured as a standalone database such as using a public SaaS offering or an existing, managed instance instead of the container provided by Kasm Technologies.

The following steps will install the ClickHouse observability database (kasm_clickhouse) on the ClickHouse Server. Once installed, ClickHouse listens for TLS connections only, published to the network on ports 8443 (HTTPS) and 9440 (secure native TCP).

  • Download the latest version of Kasm Workspaces to /tmp
  • Extract the package and execute the installation. Please note the default ClickHouse password produced during the install.
Install Files
ContentsURLSHA256
Installer Bundlehttps://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0.tar.gz7b801cb0579a7867df46b6da873fe8dd631db07d4c05349e5bd1aea27130c37d
ContentsURLSHA256
Serviceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_amd64_1.19.0.tar.gzc8697a7d6db6d6c2cd685cf431977e79bb4adfa35d91d6fab455e70f4441e46d
Workspaceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_amd64_1.19.0.tar.gz2338ed95653cf37b41c32c4202c38b507fd94a745dc81a303402e20f292486da
Network Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_network_plugin_images_amd64_1.5.tar.gzbd13ce71737cebf2e7559c01c2dbff657a52505c771fce450a32bed36ef3056d
Logging Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_logging_plugin_images_amd64_1.1.tar.gzfe5d1d6d1acd42ea89e15e375d0d6719f9d6cbf1f9c6943c4fda901a3d529135
ContentsURLSHA256
Serviceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_arm64_1.19.0.tar.gzf7975cecf89fc5b1e3886c09178047e7d6f092344ab15f9babfdeaeeb8d01801
Workspaceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_arm64_1.19.0.tar.gz5ee92ebac22c7399694c9a7eef4d0baddc98c315c2d78848fa3a757d66bcd2c4
Network Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_network_plugin_images_arm64_1.5.tar.gz59d23f6765f26be86a00fed31b38873d36f9b7b7ecf608a2efb270d969621ae6
Logging Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_logging_plugin_images_arm64_1.1.tar.gz1d720994c141fe9743b566ea2affeee77759e272ad777d0257ed6a089dd3b802
Note

If you have an activation key it can be passed to the installation script and activation will be completed on your behalf as part of the install. Create a file for the activation key e.g. activation_key.txt and paste in the activation key you received in your confirmation email. When running the install.sh use the parameter -a or --activation-key-file so your command might look something like this sudo bash kasm_release/install.sh -a activation_key.txt. This will not work with an offline air-gapped install, as Kasm Workspaces must contact an activation server to complete licensing your installation. In a multi server install this option only applies to the database role.

The clickhouse role creates two ClickHouse users: a writer user (kasm_otel) that the OTel Collector uses to write telemetry, and a read-only user (kasm_otel_ro) that the Kasm API uses for UI reports and the log viewer. The install prints both credential pairs, along with the exact --clickhouse-* flags to pass on the app/all node.

For the next steps you need the following information

  • CLICKHOUSE_PASSWORD Optional : The password to set for the kasm_otel writer ClickHouse user. If omitted, a password is auto-generated and printed at the end of the install. This same password is later passed as --clickhouse-password on the app/all node to connect.
  • CLICKHOUSE_READER_PASSWORD Optional : The password to set for the kasm_otel_ro read-only ClickHouse user. If omitted, a password is auto-generated and printed at the end of the install. This same password is later passed as --clickhouse-reader-password on the app/all node to connect.

Before continuing, verify the app/all node can access this server on ports [CLICKHOUSE_HOSTNAME]:8443 and [CLICKHOUSE_HOSTNAME]:9440

cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz.sha256sum \
&& sha256sum --check *.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/install.sh --role clickhouse --clickhouse-password [CLICKHOUSE_PASSWORD] --clickhouse-reader-password [CLICKHOUSE_READER_PASSWORD]
Note

ClickHouse always listens on TLS-only ports 8443 and 9440 on this role, published to the network so remote nodes can reach it. There is no plaintext/Docker-internal-only mode for the dedicated clickhouse role.

Install Web App Role​

The following steps will provision the Web App components on a single server. Repeat these steps on additional servers to add redundancy and scalability. Utilize a single public DNS name with multiple public IPs to have DNS load distribute requests to the Web App Kasm Workspaces server cluster.

For the next steps you need the following information

  • DATABASE_HOSTNAME : The IP, hostname or FQDN of the Database Server that is resolvable and reachable by the Web App server.
  • DATABASE_PASSWORD : The database password generated during the installation of the database.
  • DATABASE_USERNAME Optional : The database username if using a custom one. This does not need to be included if using a standard Database Server Role installation.
  • DATABASE_NAME Optional : The database name if using a custom one. This does not need to be included if using a standard Database Server Role installation.
  • CLICKHOUSE_HOSTNAME : The IP, hostname or FQDN of the ClickHouse Server that is resolvable and reachable by the Web App server.
  • CLICKHOUSE_PASSWORD : The kasm_otel writer password generated (or set) during the installation of the ClickHouse Server.
  • CLICKHOUSE_READER_PASSWORD : The kasm_otel_ro read-only password generated (or set) during the installation of the ClickHouse Server.

Before continuing, verify this server can access port [DATABASE_HOSTNAME]:5432

ClickHouse wiring

The --clickhouse-* flags in the command below point the Web App node at the ClickHouse Server over TLS, and are required in a multi-server deployment. The connection uses two credential pairs: the writer (--clickhouse-username/--clickhouse-password) that the OTel Collector uses to write telemetry over the secure native interface (9440), and the reader (--clickhouse-reader-username/--clickhouse-reader-password) that the Kasm API uses to read telemetry over the HTTPS interface (8443) for UI reports and the log viewer. Omitting the reader credential causes UI reports and the log viewer to fail authentication. Verify this server can access [CLICKHOUSE_HOSTNAME]:8443 and [CLICKHOUSE_HOSTNAME]:9440 before continuing. Retention/TTL of telemetry data is managed on the node that hosts ClickHouse, so retention flags passed to this node have no effect. The --clickhouse-endpoint value includes skip_verify=true because no certificate authority is distributed between nodes; the connection remains encrypted, but the collector does not verify the ClickHouse Server's certificate identity. This matches the Database Server's default TLS posture (sslmode=require): encrypted, without certificate verification. Add skip_verify=false instead if you distribute your own trusted CA to both nodes.

Note

Use the -z flag to set the Deployment Zone that the components will use. The zone will be created if it does not already exist in the deployment. Unless specified, components will use the "default" zone. Ex: -z east

Warning

Installation is the only time that a new Deployment Zone can be created.

  • Download the latest version of Kasm Workspaces to /tmp
  • Extract the package and run execute the installation
cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/install.sh --role app --db-hostname [DATABASE_HOSTNAME] --db-password [DATABASE_PASSWORD] --database-user [DATABASE_USERNAME]  --database-name [DATABASE_NAME] --clickhouse-endpoint "tcp://[CLICKHOUSE_HOSTNAME]:9440?secure=true&skip_verify=true" --clickhouse-http-endpoint "https://[CLICKHOUSE_HOSTNAME]:8443" --clickhouse-username kasm_otel --clickhouse-password [CLICKHOUSE_PASSWORD] --clickhouse-reader-username kasm_otel_ro --clickhouse-reader-password [CLICKHOUSE_READER_PASSWORD]
  • Log into the Web Application running on port 443 at https://<WEBAPP_SERVER>
  • The Default usernames are admin@kasm.local and user@kasm.local. The passwords will be randomly generated and presented at the end of the install unless the --admin-password or/and --user-password are specified.

Default Login Window

Default Login Window

Install Agent Server Role(s)​

The following steps will install the Agent and Proxy services. Repeat these steps for any additional servers intended to provision end user sessions

For the next steps you need the following information

  • MANAGER_HOSTNAME : The IP, hostname or FQDN of the Web App Server that is resolvable and reachable by the Agent server.
  • MANAGER_TOKEN : The manger token generated during the db install. This is used for authentication by the Agent.
  • AGENT_HOSTNAME : This IP, hostname, or FQDN of this Agent Server that is resolvable and reachable by the Web App Server. This value will be reported by the Agent Service during check in routines and used by other services to communicate with it.
  • OTEL_TOKEN : The OTel token generated during the App role install, used to authenticate telemetry sent by remote roles.

Before continuing, verify this server can access ports [MANAGER_HOSTNAME]:443 and [MANAGER_HOSTNAME]:4317

  • Download the latest version of Kasm Workspaces to /tmp
  • Extract the package and execute the installation
cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/install.sh --role agent --public-hostname [AGENT_HOSTNAME] --agent-registration-hostname [MANAGER_HOSTNAME] --agent-token [MANAGER_TOKEN] --otel-token [OTEL_TOKEN] --otel-collector-hostname [MANAGER_HOSTNAME]

  • Log into the UI as an Administrator, select Infrastructure > Docker Agents and using the arrow menu select edit on the agent you just created. Make sure Enabled is selected and click Save.

    Update Agent
    Update Agent

(Optional) Install Connection Proxy (Guac/rdp-gateway) Role(s)​

The Connection proxy role is required to support connecting to VMs/Hardware via RDP, VNC, or SSH. Workspace supports connecting to pre-exiting machines or auto provisioning them via Cloud Autoscaling. If these services are not needed, this role does not need to be installed.

For the next steps you need the following information

  • MANAGER_HOSTNAME : The IP, hostname or FQDN of the Web App Server that is resolvable and reachable by the Agent server.
  • SERVICE_REGISTRATION_TOKEN : The registration token generated during the db install. This is used to register the Connection Proxy with the system. The Service Registration Token (AKA Component Registration Token) can also be found in the global settings in the Kasm Admin UI.
  • CONNECTION_PROXY_HOSTNAME : This IP, hostname, or FQDN of this Connection Proxy Server that is resolvable and reachable by the Web App Server. This value will be reported by the Connection Proxy Server during registration and used by other services to communicate with it.
  • OTEL_TOKEN : The OTel token generated during the App role install, used to authenticate telemetry sent by remote roles.

Before continuing, verify this server can access ports [MANAGER_HOSTNAME]:443 and [MANAGER_HOSTNAME]:4317

Note

Use the -z flag to set the Deployment Zone that the components will use. Unless specified, components will use the "default" zone. Ex: -z east

  • Download the latest version of Kasm Workspaces to /tmp
  • Extract the package and execute the installation
cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/install.sh --role guac --api-hostname [MANAGER_HOSTNAME] --public-hostname [CONNECTION_PROXY_HOSTNAME] --registration-token [SERVICE_REGISTRATION_TOKEN] --otel-token [OTEL_TOKEN] --otel-collector-hostname [MANAGER_HOSTNAME]
Observability flags

All nodes in a distributed deployment must share the same OTel bearer token (--otel-token). Specify --otel-collector-hostname on remote roles to point them to the app/all node. For the full flag reference and offline image pre-pulls, see the Observability configuration reference page.

By default, the inter-collector hop (port 4317) between each remote node's collector and the central collector on the app/all node is bearer-token authenticated and TLS-encrypted, without certificate verification. If the app/all node was installed with a CA-signed certificate (--ssl-public-cert/--ssl-private-key) whose SANs cover the exact hostname passed as --otel-collector-hostname, add --otel-collector-verify-tls (public CA) or --otel-collector-ca-cert <path> (private/corporate CA) to the remote role's install command to turn on certificate verification for that hop, for example:

sudo bash kasm_release/install.sh --role guac --api-hostname kasm-app.example.com --public-hostname 192.0.2.20 --registration-token [SERVICE_REGISTRATION_TOKEN] --otel-token [OTEL_TOKEN] --otel-collector-hostname kasm-app.example.com --otel-collector-ca-cert /path/to/corporate-ca.pem

See "Configure custom TLS certificates" in the Deploy and manage observability guide for the full prerequisites and procedure.

For offline installs, pre-pull these two new container images before running the installer:

docker pull otel/opentelemetry-collector-contrib:0.160.0
docker pull clickhouse/clickhouse-server:24.12-alpine

Note: kasm_clickhouse is deployed only on a single-server all node, or on a dedicated clickhouse role node. The app role never bundles ClickHouse and must connect to a dedicated or external instance. kasm_otel_collector is not deployed on clickhouse role nodes.

All install options
FlagDescription
-h, --helpDisplay the help menu
-V, --install-profileInstallation profile to use (kasm_release/profiles)
-S, --roleRole to install: [all|app|db|agent|init_remote_db|guac|proxy|clickhouse]
-L, --proxy-portDefault proxy listening port
-v, --verboseVerbose output
-e, --accept-eulaAccept End User License Agreement
-d, --no-db-initSkip database initialization
-D, --no-startDon't start services at the end of installation
-W, --default-imagesSeed and Download default Workspaces Images
-z, --server-zoneServer Zone (Deployment Zone for components)
-q, --db-hostnameDatabase Hostname
-Q, --db-passwordDefault Database Password
-c, --database-userDatabase user
-j, --database-nameDatabase name
-t, --no-db-sslDatabase, Disable SSL
-T, --db-portDatabase port for external DB (default 5432)
-U, --user-passwordDefault User Password
-P, --admin-passwordDefault Admin Password
-p, --public-hostnameAgent/Component IP/Hostname used to register with deployment
-m, --agent-registration-hostnameHostname or IP of the Web App that the agent registers with
-M, --agent-tokenAgent token, printed by the Web App install
-i, --agent-server-idSet Agent server ID
-n, --api-hostnameSet API server hostname
-a, --activation-key-fileLicense Activation key file path
-w, --offline-workspacesPath to the tar.gz workspace images offline installer
-s, --offline-servicePath to the tar.gz service images offline installer
-x, --offline-network-pluginPath to the tar.gz network plugin images offline installer
--offline-logger-pluginPath to the tar.gz logger plugin images offline installer
-O, --use-rolling-imagesUse rolling Workspaces images
-f, --use-static-imagesUse static version Workspaces images
-F, --use-tagUse a specific tag for service images (defaults to the build date)
-G, --db-master-passwordDatabase master password for database remote init
-g, --db-master-userDatabase master user for database remote init
-r, --agent-providerSet agent provider
-A, --enable-losslessEnable lossless streaming option
-k, --registration-tokenRegister a component with an existing deployment
-y, --default-registry-urlSet the default Workspaces Registry URL
-H, --no-swap-checkDisable check for swapfile
-J, --swap-sizeCreate swap if none exists in megabytes (e.g., 4096)
-B, --no-check-portsDo not check for open ports
-b, --no-check-diskDo not check disk space
-N, --skip-connection-testSkip database connection tests
-X, --skip-v4l2loopbackSkip v4l2loopback installation
--guac-cluster-sizeSet guac cluster size, 0 for automatic
--skip-custom-rcloneInstall the stock Rclone plugin without modification
--skip-egressDo not install egress network plugin or dependencies
--enable-epelEnable EPEL repo to install packages not in default RHEL repos. Required for WireGuard on RHEL/Rocky/AlmaLinux/Oracle 8 — pass this flag explicitly or respond y to the interactive prompt.
--ignore-dep-failuresContinue installation even if optional dependencies fail to install
--install-dependsForce dependency installation even during offline installs. Has no effect on online installs (deps always run by default).
--ssl-public-certCopy the public SSL certificate from this path during install
--ssl-private-keyCopy the private SSL key from this path during install
--skip-otelDo not install the OTel Collector or ClickHouse
--otel-tokenBearer token for inter-collector authentication — must be identical on every node in a distributed deployment (auto-generated if omitted)
--otel-collector-hostnameHostname of the central collector node (app/all role) — required on remote roles (agent, guac, proxy)
--otel-collector-verify-tlsVerify the central collector's certificate on the inter-collector hop (4317) instead of skipping verification. Set on remote roles (agent, guac, proxy); no effect on db/all/app/clickhouse. Requires a CA-signed cert on the app/all node whose SANs cover --otel-collector-hostname
--otel-collector-ca-certCA certificate to trust for that verification; implies --otel-collector-verify-tls. Use for a private/corporate CA
--otel-collector-endpointUse a custom OTLP/HTTP collector (e.g. Grafana Alloy) instead of the bundled one; app/all roles only
--clickhouse-endpointNative-interface DSN of a dedicated or external ClickHouse; requires --clickhouse-http-endpoint. Set on app/all roles — required on app (the role never bundles ClickHouse) unless --no-clickhouse is set; removes the bundled container on all
--clickhouse-http-endpointHTTP(S) URL of the same dedicated or external ClickHouse, read by the Kasm API for UI reports and the log viewer. Set on app/all roles — required on app unless --no-clickhouse is set
--clickhouse-usernameUsername for the dedicated or external ClickHouse database (default: kasm_otel)
--clickhouse-databaseClickHouse database name (default: kasm_otel); independent of --clickhouse-username — set both for a tenant-specific database
--clickhouse-passwordSets the ClickHouse server password on the clickhouse role, or the bundled ClickHouse's password on all. On app, this is the connect password used to reach the required dedicated or external ClickHouse
--clickhouse-reader-usernameRead-only username for the dedicated or external ClickHouse database, used by the Kasm API for UI reports and the log viewer (default: kasm_otel_ro)
--clickhouse-reader-passwordSets the read-only ClickHouse server password on the clickhouse role, or the bundled ClickHouse's read-only password on all. On app, this is the connect password used to reach the required dedicated or external ClickHouse
--no-clickhouseOn all, do not deploy the bundled ClickHouse. On app, run the node without any ClickHouse (debug exporter mode) instead of requiring a dedicated or external one. Mutually exclusive with --clickhouse-endpoint/--clickhouse-http-endpoint
--otel-forward-endpointAdditionally forward all telemetry to this OTLP/HTTP endpoint (e.g. a remote Grafana Cloud instance)
--otel-forward-tokenBearer token for --otel-forward-endpoint
--otel-trace-sample-percentagePercentage (0–100) of non-error, non-slow traces to retain (default: 10)
--otel-logs-retention-daysGeneral log retention in days (default: 30)
--otel-audit-logs-retention-daysAudit log retention in days (default: 365)
--otel-traces-retention-daysTrace retention in days (default: 7)
--otel-metrics-retention-daysMetrics retention in days (default: 90)

Dedicated Kasm Proxy (optional)​

In a standard Multi Server installation the Proxy service that handles pointing the client to the correct agent server is included with the Web App role along with all other client UI and routing. The need might arise to have many proxies spread out over different geographic locations while keeping a single web endpoint serving static web content with the Proxy serving the Kasm Workspaces session. To facilitate this there is a proxy installation role that installs and configures a web proxy to direct end users to the correct agent to spin up a Kasm Workspaces session.

Proxy Overview​

Proxy Workflow
Proxy Workflow

The user follows the same workflow when launching a workspace and on the backend we direct them to the correct Agent/s, but unlike a standard Multi Server Deployment the Workspaces Session is routed through the Proxy in the user's geographic region to reduce latency.

Proxy installation​

Note

This guide assumes you have a running Multi Server deployment of Kasm Workspaces and have a basic understanding of domain/SSL management. For help with SSL certificates please see Custom Certificates

The following steps can be followed to install the proxy role to a server:

  • Ensure the Proxy server has a domain name pointed to it and a legitimate SSL certificate.
  • Download the latest version of Kasm Workspaces to /tmp.
  • Extract the package and execute the installation.
  • Post install, configure Kasm Workspaces via the Web UI to use the new Proxy.

In this example we assume the proxy domain is proxy.example.com and the Web App hosting the API server is located at workspaces.example.com.

Proxy Server installation​

Note

It is important that the agents in your Multi Server installation can be accessed by this Proxy server deployment ensure connectivity to the Agent server from the Proxy server before installation.

In order to install the proxy role you will need the following information:

  • Web App server URL — the hostname of the server running the app role (for example, workspaces.example.com). This endpoint is used for authentication and is required to enforce strict CORS policies.
  • OTel bearer token — the shared --otel-token value configured on the app node. Pass the same token here so this proxy node reports telemetry to the same collector.
cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release*-latest.tar.gz \
&& sudo bash kasm_release/install.sh --role proxy --api-hostname workspaces.kasmweb.com --otel-token [OTEL_TOKEN] --otel-collector-hostname workspaces.kasmweb.com

Post Install Configuration​

With the proxy running you will need to login to your Kasm Workspaces installation as an administrator and navigate to Admin->Settings->Global->Authentication->Kasm Auth Domain. Change this setting to example.com and click Save.

Set Auth Domain
Set Auth Domain

Next navigate to Admin->Infrastructure->Zones->Click the arrow next to the zone you want to point to the Proxy->Edit Set Proxy Hostname to proxy.example.com

Set Proxy Host
Set Proxy Host

While in this menu also set Upstream Auth Address to workspaces.example.com

Set Upstream Auth
Set Upstream Auth

With these setting changed we need to restart the API server container on the Web App server/s:

sudo docker restart kasm_api

When a user now deploys a Kasm Workspace their streaming session will be served up by this new external proxy instead of the default one deployed with the Web App role.

Install troubleshooting​

The install.sh script creates a log file as it runs, this file is removed upon completion of a successful installation. However, if something does go wrong the logfile will be available from the directory the install.sh script was executed from in the format kasm_install_${TIMESTAMP}.log. This file will be important for diagnosing the error that caused the installation to fail and will be requested when submitting a support ticket with Kasm Technologies.