Kasm Desktop Service for Windows

The Kasm Desktop Service for Windows is a service that adds capabilities for users connected to a desktop through Kasm Workspaces:

• Upload files to the remote desktop.
• Download files from the remote desktop.
• Show a preview screenshot of the desktop in the Kasm Workspaces dashboard.
• Run PowerShell scripts on session start, session end, or service start.
• Manage local Windows users and credentials.
• Map files through File Mapping.
• Support multiple concurrent users on the same Windows system.

System requirements

Supported operating systems
Windows 10 (x86_64)
Windows 11 (x86_64)
Windows Server 2019 (x86_64)
Windows Server 2022 (x86_64)
Windows Server 2025 (x86_64)

Installation

Install the Kasm Desktop Service with one of the installers below. The installer places all files in C:\Program Files\Kasm. Use the latest version that supports your installed version of Kasm Workspaces.

Installer version	Installer link	Kasm Workspaces compatibility	SHA256
Developer Preview	kasm_windows_service_installer_x86_64_develop.exe	Developer Preview	rolling
1.8.8e3b288d3	kasm_windows_service_installer_x86_64_1.8_8e3b288d3.exe	1.19.0	04a4650a1ba5465b97159be62a4db7d246b92c813c3550e842ebb1e70521c21e
1.7.c54746a56	kasm_windows_service_installer_x86_64_1.7_c54746a56.exe	1.18.0, 1.18.1	cfb3fc77d624a9e664eef536b1f4160e0bab90ee923d2067a291d89187dcba02
1.6.8c568cfb1	kasm_windows_service_installer_x86_64_1.6_8c568cfb1.exe	1.16.0, 1.16.1, 1.17.0	4b2eba790ba45af4ddd6d202894ee25b6b904ce4de0f0ea1c3892a35c6c2d40e
1.5.5972ac21d	kasm_windows_service_installer_x86_64_1.5_5972ac21d.exe	1.16.0, 1.16.1, 1.17.0	6485ce5743046f02c27cb22628559ac81ad3bc5a413cdf44735bffca28bdca70
1.4.7f51b2de	kasm_windows_service_installer_x86_64_1.4_7f51b2de.exe	1.16.0, 1.16.1, 1.17.0	9b6739385a4a55244bf46fd26f0c7465a395a5a5c67f9da6d118232a417a6758
1.3.af09998b6	kasm_windows_service_installer_x86_64_1.3.af09998b6.exe	1.16.0	f7c18cf85570143a840e1e4d151f858e5352fbc2fd0f9fe90db02f9de7f29494
1.2.22550d18	kasm_windows_service_installer_x86_64_1.2.22550d18.exe	1.15.0	afa6705c502b63c2610b93d8ded81f05f47d094d15964bf30d1ab523da20ccb3
1.1.2b3f26b	kasm_windows_service_installer_x86_64_1.1.2b3f26b.exe	1.14.0	51b2a83d63a0ccf7634272e68695bbd37731a57bb06b28482471e2f75d925d40
1.0.616b3bea	kasm_windows_service_installer_x86_64_1.0.616b3bea.exe	1.12.0, 1.13.0, 1.14.0	5022bf6b9f508447c5913b6ed336646c624edb095c1083460e0d780f4a54a02a
0.9	kasm_windows_service_installer_x86_64_02beec.exe	1.12.0, 1.13.0	ea20d43129c3145306922e05b2643cadf6bc04ec6d66539979b3cc16dfbb4e21
0.8	kasm_windows_service_installer_x86_64_5a2950.exe	1.12.0, 1.13.0	9f514b913a9ebff1686695f3bf430958a59776c7bb1c5d0cac98a3510769ed67

Use the developer preview build of the Kasm Desktop Service only with the developer preview build of Kasm Workspaces, and only on non-production systems. The documentation on this page reflects the latest installer version in the table and may not be accurate for older versions.

The Kasm Desktop Service uses HTTPS to communicate with the other Kasm Workspaces services. The installer opens the Windows firewall for TCP port 4902. Allow inbound TCP port 4902 from the Kasm API server and Connection Proxy servers. The service connects outbound to the API server, on TCP port 443 by default. Allow this outbound connection in firewalls and security groups.

These instructions apply to static Windows servers. AutoScaled servers install the service through the PowerShell startup scripts. For more details, see AutoScaled servers startup scripts.

Install and register the service

1. Sign in to Kasm as an administrator.

2. Create a new server. You can optionally add the server to a pool.

3. Enable the Kasm Desktop Service Installed option when you create the server.

4. On the Windows server, download the appropriate version of the Kasm Desktop Service from the table above.

5. Launch the Kasm Desktop Service installer. The installer prompts you for information.

   

   Kasm Desktop Service installer settings dialog

6. Enter the hostname or IP address of the Kasm API (Web App role) services. This is normally the same hostname or IP address that end users use to access the deployment.

7. Enter the port number for Kasm Workspaces. The default is port 443.

8. Provide the registration token for this server. In the Kasm Admin UI, go to Infrastructure > Servers > Servers, find the target server, and click Edit. In the Kasm Agent section, click the copy button on the Registration Token field, then paste the value into the installer Registration Token field.

   

   Registration Token field in the Kasm server Agent settings

9. Optional: enter the API path prefix if the deployment is hosted behind a path-based proxy, for example /kasmapp.

10. Click Ok after you fill in the required information. When registration completes, the dialog closes and the installer shows completion. Close the installer.

    

    Kasm Desktop Service installer completion dialog

Installation troubleshooting

During installation, the Kasm Desktop Service registers itself with the Kasm Workspaces deployment using the registration token. The registration process performs the following checks:

• The Kasm Desktop Service can reach the Kasm Workspaces deployment on the specified port and hostname.
• The Kasm Workspaces deployment can reach the Kasm Desktop Service on port 4902, using the hostname or IP address in the server record.
• The registration token is digitally signed by the deployment, is not expired, and is assigned to the server being registered.

When any check fails, the installer shows an error after you click Ok. Correct issues such as DNS resolution of the hostname, firewall rules, or expired registration tokens, then click Ok to try again.

Kasm Desktop Service installer registration error dialog

Scripted installation

You can script the installation and registration of the Kasm Desktop Service. In the example below, replace kasm.example.net with the hostname or IP address of your deployment, set the port number if it differs from 443, and provide the registration token for the server.

# Download the appropriate version of the Kasm installer from the table above
kasm_windows_service_installer_x86_64_1.2.22550d18.exe /S
net stop kasm
cd "C:\Program Files\Kasm"
.\agent.exe --register-host kasm.example.net --register-port 443 --register-token "<registration-token>"
net start kasm

caution

The installation directory C:\Program Files\Kasm inherits Windows ACL permissions from the parent directory. For the best security, confirm that standard users do not have read access to the installation directory, because the directory contains potentially sensitive information.

Server enrollment tokens

To install the Kasm Desktop Service and register it with a server enrollment token, follow the installation steps through step 7, then replace step 8 with the following.

8. Provide the registration token for this server. In the Kasm Admin UI, go to Infrastructure > Servers > Server Enrollment Tokens, find the target server, click the copy button on the Token field, then paste the value into the installer Registration Token field.

   

   Server Enrollment Tokens list with the Token copy button

Scripted installation with an enrollment token

When you script registration with an enrollment token, an additional step is required. Run the agent in the background before you attempt registration.

#ps1
Start-Process <PATH_TO_DOWNLOADED_INSTALL_FILE> -ArgumentList "/S" -Wait
net stop kasm
Start-Process agent.exe -ArgumentList "--cfg config.yaml" -WorkingDirectory "C:\\Program Files\\Kasm"
Start-Sleep -Seconds 2
Start-Process agent.exe -ArgumentList "--register-host <KASM_API_HOSTNAME> --register-port 443 --register-token <SERVER_ENROLLMENT_TOKEN>" -Wait -WorkingDirectory "C:\\Program Files\\Kasm"
Stop-Process -Name agent -Force
net start kasm

The server hostname value is used to connect to the server, but it cannot currently be templated and must be detected dynamically. Kasm first attempts to connect using the server's FQDN. When that attempt fails, Kasm attempts the request IP address. When both attempts fail, enrollment fails.

Optional dependencies

Kasm uses WinFsp to support cloud storage mappings in Windows. Download the latest Windows MSI installer from the WinFsp release page. Alternatively, install WinFsp non-interactively with the following PowerShell script.

$winfsp_url = "https://github.com/winfsp/winfsp/releases/download/v2.0/winfsp-2.0.23075.msi"
$winfsp_msi = "winfsp-2.0.23075.msi"

Function Install-Winfsp {
  Invoke-WebRequest -Uri $winfsp_url -OutFile $Env:temp\$winfsp_msi
  Write-Host "Installing WinFSP"
  Start-Process -FilePath $Env:temp\$winfsp_msi -ArgumentList '/q' -WorkingDirectory "C:\Windows\Temp\" -Wait
  Remove-Item $Env:temp\$winfsp_msi -Force
}

Install-Winfsp

SSL certificates

The installation assigns an SSL certificate to the service. Kasm uses a self-signed certificate by default. You can replace the auto-generated self-signed certificates with certificates signed by your organization's certificate authority. The certificate and key must be in PEM format and are stored at C:\Program Files\Kasm\certs.

Upgrade

Running the installer on a machine with an existing Kasm Desktop Service performs an upgrade. The upgrade preserves the existing configuration file, the certificates, and any files in the upload and download folders.

Uninstall

To uninstall the Kasm Desktop Service, open Add or remove programs or Apps & features on the Windows server, select Kasm - KasmAgent <agent version number>, then select Uninstall. A dialog box asks you to confirm the removal. Click OK to continue.

caution

The uninstall process deletes all files under C:\Program Files\Kasm.

Configuration

The following example shows the configuration with the appropriate settings annotated. The registration process generates this file automatically, but you can override it for custom deployments. Use absolute paths without trailing slashes, escape each backslash with a backslash, and make sure the referenced PEM certificate files do not contain Windows carriage returns.

# server HTTP(s) configuration
ssl: true
port: 4902
server_private_key: "C:\\Program Files\\Kasm\\certs\\key.pem"
server_public_key: "C:\\Program Files\\Kasm\\certs\\cert.pem"

# path to JWT's RSA certificate for token verification
jwt_public_key: "C:\\Program Files\\Kasm\\certs\\jwt.pem"

# path to upload/download folders
upload_dir: "C:\\Program Files\\Kasm\\Upload"
download_dir: "C:\\Program Files\\Kasm\\Download"

# (optional) path to the log file
log_file: "C:\\Program Files\\Kasm\\log.txt"

# (optional) path prefix for API requests if Kasm is hosted behind a path-based proxy
api_url_prefix: /kasmapp

# Settings for multiple user machines
multi_user: false
user_sso: false

debug: false

Settings

Name	Description
ssl	Enables SSL for the service. Kasm Workspaces supports communication with this service over SSL only.
port	The port to run the service on. Kasm Workspaces uses port 4902 for this service by default.
server_private_key	The private key used for the SSL service.
server_public_key	The public key used for the SSL service.
jwt_public_key	The public key used to authenticate API calls received from Kasm Workspaces.
upload_dir	Directory for files uploaded by users.
download_dir	Directory that users can download files from.
log_file	Optionally writes logs to this file. Logs can also be viewed in Windows Event Viewer.
multi_user	Boolean indicating that the Windows instance supports multiple users.
user_sso	Boolean indicating that Kasm users are mapped to Windows users through SSO.
api_host	The hostname or IP address of an API server or load balancer in front of the Kasm API servers.
api_port	The port number used for the deployment's API servers, port 443 by default.
api_url_prefix	Optional. The path prefix for API requests if Kasm is hosted behind a path-based proxy, for example /kasmapp.
registered	Indicates whether the agent is already registered with the deployment.
script_path	Directory where scripts are located.
server_id	The UUID of the server in Kasm Workspaces.
debug	Enables verbose logging.

Kasm updates multi_user and user_sso automatically when the service checks in with the deployment, based on the server configuration in Kasm Workspaces.

Uploads and downloads on multi-user systems

When a user uploads files from their local computer to the remote Kasm Windows session, Kasm places the files in the Downloads directory of their home path. When a user downloads a file from the remote Kasm Windows session, the control panel displays the files in the Downloads directory of their home path.

Security concerns can arise when Kasm and the Windows environment are not set up for SSO, through LDAP SSO, static accounts, Kasm-managed Windows accounts, or smartcard authentication. When all users connect to the remote Windows server with the same credentials, they all share the same Windows profile.

caution

With Prompt User authentication over Web Native RDP, Kasm does not place uploaded and downloaded files in the user's Windows profile directory, for example C:\Users\<username>\Downloads. Instead, files are stored in the default upload and download directories configured for the Kasm Desktop Service on the Windows server.

Service authentication

Every request to the application must contain a JWT token parameter, which Kasm verifies against the provided JWT key. The JWT key, also called the API Cert, is generated when Kasm Workspaces is installed and can be retrieved from the Kasm Settings panel.

API certificate in the Kasm Settings panel

The public JWT token is retrieved during registration. When you change the JWT certificate and key on the deployment, re-register the Kasm Desktop Service.

Scripts

Kasm uses a number of PowerShell scripts and provides administrators hooks to run their own PowerShell scripts during certain events. When the Kasm service runs a PowerShell script, it injects PowerShell variables so that the script has access to contextually relevant information. For more details, see the variables section.

The default location for scripts is C:\Program Files\Kasm\scripts. Use File Mapping to manage custom scripts in the Kasm UI. This directory contains the following subdirectories.

Script directories

Directory	Description
builtin	Scripts run by the Kasm service to perform specific actions. See the following section for details.
service_startup	Scripts placed here run automatically when the Kasm service starts.
session_start	Scripts placed here run automatically before a user session starts.
session_end	Scripts placed here run automatically before a user session ends.
registry	Registry setting export files.

Built-in scripts

The following built-in scripts exist for the stated purpose.

create_local_account.ps1 runs during session creation when dynamic local account SSO is configured. The script creates a local Windows account for the requesting user if one does not already exist, then retrieves a one-time random password for the account. The API call that retrieves the one-time password uses a JWT token defined in a built-in variable. The JWT token has a short expiration and can be used only once to retrieve the password.

logoff_user.ps1 logs the user off the Windows session when the user deletes their Kasm session.

load_persistent_profile.ps1 runs during session creation, before a user connects and after create_local_account.ps1 runs if required. The script is empty in the current version. It provides administrators a hook to load persistent profiles for users with third-party solutions. The script has access to the built-in variables defined below.

save_persistent_profile.ps1 runs during session termination, after the user is logged out. The script is empty in the current version. It provides administrators a hook to save persistent profiles for users with third-party solutions. The script has access to the built-in variables defined below.

map_storage.ps1 runs during session creation, before a user connects and after create_local_account.ps1 runs if required. The script maps cloud storage definitions for users. The script has access to the built-in variables and to a storage_mapping variable, which contains the storage mapping definition in JSON format. Kasm calls the script for each storage mapping that applies to the user creating the session. Kasm places all Windows storage mappings on the user's desktop. For example, a storage mapping with a target of /OneDrive maps to C:\Users\<username>\Desktop\OneDrive on a Windows system. This script requires WinFsp.

unmap_storage.ps1 runs during session termination, after the user is logged off. The script removes any mapped cloud storage volumes that map_storage.ps1 added. The script has access to the built-in variables and to a storage_mapping variable, which contains the storage mapping definition in JSON format. Kasm calls the script for each storage mapping that applies to the user creating the session.

Variables

The following variables are built in and available to any PowerShell script run by the Kasm service.

Name	Description
user_id	The Kasm User ID for the user creating or terminating the session.
username	The Windows username of the user creating or terminating the session.
kasm_id	The Kasm session ID for the session being created or terminated.
jwt_token	A limited-access, short-lived JWT token that can be used to make API calls to Kasm.
api_host	The IP address or hostname of the API server or load balancer for the API servers.
api_port	The port number of the API server.
api_url_prefix	Optional. The path prefix for API requests if Kasm is hosted behind a path-based proxy.
ts_session_id	The associated Windows Terminal Session ID.
is_remote_app	Indicates whether the session is a RemoteApp.
is_web_native	Indicates whether the session uses Kasm web native access or an RDP client.
auto_logout_user	Indicates whether the Kasm Desktop Service logs the user out automatically when the session closes.

Reference these variables in administrator-defined PowerShell scripts as follows.

Write-Host "Session starting for $username"

Kasm logs the full output of scripts when the exit code is a non-zero value or when debug is enabled in the configuration.

Logging

By default, Kasm writes all log messages to the Windows event log, under Applications > KasmService. To redirect logs to a file, specify the log_file parameter in config.yaml. Kasm also sends logs to the deployment, where you can search them in the Kasm Admin UI under Diagnostics > Logging.

Manage registry settings

Use File Mappings to map registry setting export files to C:\Program Files\Kasm\scripts\registry. These files must end in .reg and should be exports created by Microsoft regedit. When the Kasm Desktop Service starts, it downloads new file mappings and applies any .reg files in that directory. For example, use this approach to configure RDP settings for systems outside a domain.