Skip to main content
Version: Developer

Configure Direct to Agent connections in Kasm Workspaces

Overview​

By default, Kasm Workspaces proxies every session connection through the Web App role to the Agent role. The proxy reduces complexity and works well for most deployments. At higher concurrency, routing all session traffic through the Web App adds latency and consumes Web App bandwidth that scales with every active session. This guide configures the Direct to Agent connection mode, so clients connect straight to the Agent and the Web App no longer carries session traffic. The result is lower latency and a Web App tier that scales independently of session load.

Diagram comparing the proxied connection workflow with the Direct to Agent workflow

Connection workflows

Prerequisites​

  • A working Kasm Workspaces deployment in a multi-server configuration.
  • Administrator access to the Workspaces UI.
  • Shell access to every Agent and Web App server with permission to run sudo systemctl.
  • DNS records that resolve every Web App and Agent server within the same parent domain, for example app-1.kasm.example.com and agent-1.kasm.example.com.
  • Network paths that allow clients and Kasm role servers to reach each Agent and Web App address over HTTPS.
  • Valid certificates on every Web App and Agent server that clients trust. To install them, see Replace certificates.

Solution approach​

This guide progresses through the following phases:

  1. Register each Agent under its DNS name.
  2. Disable proxy connections and set the authorization domain.
  3. Validate that clients connect directly to the Agent.

Detailed steps​

Register each Agent under its DNS name​

Configure each Agent to register with the Workspaces system using its public DNS name rather than its internal address. Repeat the following steps on every Agent.

  1. Stop the services on the Agent.

    sudo systemctl stop kasm

  2. Open the Agent configuration file.

    sudo vi /opt/kasm/current/conf/app/agent/agent.app.config.yaml

  3. Set the public_hostname value to the public DNS name of the Agent, for example agent-1.kasm.example.com.

  4. Start the services on the Agent.

    sudo systemctl start kasm

  5. Log in to the Workspaces UI as an administrator, then select Infrastructure > Docker Agents. Confirm that the Agent checks in under its DNS name.

Disable proxy connections and set the authorization domain​

Turn off proxying for the applicable Zone, then point the authorization domain at the parent domain that the Web App and Agent servers share.

  1. Log in to the Workspaces UI as an administrator.

  2. Select Infrastructure > Zones, then select Edit next to the applicable Zone.

  3. Clear the Proxy Connections checkbox, then select Save.

    Zone settings with the Proxy Connections checkbox cleared

    Zone configuration

  4. Select Settings > Global from the Admin panel.

  5. Set Kasm Authorization Domain to the parent domain of the Web App and Agent servers, for example kasm.example.com.

    Global settings showing the Kasm Authorization Domain field

    Authorization domain

  6. Restart the services on every Web App server.

    sudo systemctl restart kasm

Validate that clients connect directly to the Agent​

Confirm that new sessions route to the Agent address rather than the Web App.

  1. Log out of the Workspaces UI.

  2. Open a new incognito browser window, then log in to the Workspaces UI.

  3. Open the browser developer tools, select the Network tab, then enter vnc.html in the filter.

  4. Launch a new session. The request URL in the developer tools shows the Agent address as the domain.

    Browser developer tools showing the Agent address as the request domain

    Developer tools

Common troubleshooting steps​

  • The Agent checks in under an internal address. Confirm that public_hostname is set to the public DNS name in agent.app.config.yaml, then restart the Agent services.
  • Sessions fail to load after disabling the proxy. Confirm that clients resolve each Agent DNS name and reach it over HTTPS on the configured port.
  • The browser reports a certificate error on the Agent address. Confirm that the Agent presents a certificate that clients trust. See Replace certificates.
  • Session requests still route through the Web App. Confirm that Proxy Connections is cleared on the correct Zone and that the Web App services restarted after the change.