Skip to main content
Version: Developer

SSH-agent passthrough

Overview​

Development workflows often depend on SSH keys already loaded in a local SSH agent for ssh, git over SSH, and SSH-based Git commit signing. This guide enables SSH-agent passthrough for container-based Kasm Workspaces, so a workspace session reaches the user's local SSH agent and the identities it already holds. As a result, users run ssh, push over SSH, and sign commits from inside an isolated container while their private key material stays on the local device.

caution

SSH-agent passthrough is under active development. It becomes available for external testing in the Kasm Workspaces 1.20.0 rolling images once the underlying components merge into the develop branches. It is not available in any static or generally available release yet. Confirm current availability before relying on this guide in production.

For forwarding a physical FIDO2 security key instead of an SSH agent, see FIDO2 security key passthrough.

Prerequisites​

Before you begin, confirm the following:

  • Kasm Workspaces 1.20.0 or later.
  • A container-based Kasm Workspaces workspace built from a workspace image with SSH-agent passthrough support installed.
  • Administrator access to the Kasm Workspaces deployment, with permission to manage Group Settings.
  • A supported client platform: Windows or macOS, with the Kasm Native Smartcard Client installed. SSH-agent passthrough reuses the same native client used for smart card passthrough.
  • A running local SSH agent on the user's device, such as ssh-agent, 1Password's SSH agent, or the Windows OpenSSH agent, with the intended keys already loaded before the session launches.

Solution approach​

This guide progresses through the following phases:

  1. Enable SSH-agent passthrough for user groups.
  2. Confirm the Kasm Native Smartcard Client is installed on the user's device.
  3. Verify SSH-agent passthrough.

Detailed steps​

Enable SSH-agent passthrough for user groups​

The allow_kasm_ssh_agent_passthrough Group Setting controls SSH-agent passthrough, independent of smart card and FIDO2 passthrough. The setting is disabled by default and applies only to container-based workspaces.

  1. In the Kasm Workspaces UI, open the Group Settings for the relevant group.
  2. Set the allow_kasm_ssh_agent_passthrough Group Setting to true.
  3. Apply this setting before users launch any session that requires SSH-agent passthrough. The setting takes effect the next time a user in the group launches a session.

The Group Setting sets the KASM_SVC_SSH_AGENT environment variable on the user's session container. When a Session Casting configuration has Enforce Client Settings enabled, its Allow Kasm SSH Agent Passthrough option overrides the Group Setting for sessions launched from that casting link. For Session Staging, enable Allow SSH Agent Passthrough on the staging configuration so that staged sessions match the users who require passthrough.

caution

Setting KASM_SVC_SSH_AGENT=1 in a Workspace's Docker Run Config Override also enables SSH-agent passthrough. That environment variable takes precedence over the Group Setting, so it enables passthrough for every user who launches the Workspace, regardless of group membership. Use the Group Setting to control access by group.

Confirm the Kasm Native Smartcard Client is installed​

  1. Download and install the Kasm Native Smartcard Client. Follow the instructions in the Kasm Native Smartcard Client section of the smart card passthrough guide.
  2. If the user already has the native client installed and up to date for smart card or FIDO2 passthrough, no additional installation is required.
  3. Confirm the local SSH agent is running on the user's device and has the intended keys loaded before starting a session.

Verify SSH-agent passthrough​

  1. Launch a container-based Kasm session as a user whose group has allow_kasm_ssh_agent_passthrough enabled.
  2. Inside the workspace, open a terminal and run ssh-add -l. The output lists the same identities loaded in the user's local agent.
  3. Test an operation that depends on the forwarded agent, such as ssh to a reachable host, git push over SSH, or git commit -S with gpg.format=ssh configured to sign with an SSH key.

Technical implementation​

SSH-agent passthrough uses the same native client as smart card and FIDO2 passthrough, paired with a persistent bridge process inside the container.

  • Kasm SSH-agent bridge (kasm_ssh_agent_bridge, inside the container) is a persistent daemon started at session startup. It listens on a Unix domain socket that becomes the session's $SSH_AUTH_SOCK, and accepts concurrent connections from multiple guest processes, such as ssh, git, and ssh-keygen -Y sign.
  • KasmVNC carries traffic between the container and the user's device over a dedicated relay channel. Because multiple guest connections can be open at once, each relay packet carries a connection identifier so responses reach the correct guest connection.
  • Kasm Native Smartcard Client proxies each connection, by connection identifier, to the user's local SSH agent and relays the raw SSH-agent protocol frames unchanged in both directions. The native client does not parse SSH-agent protocol content.

The communication flow is: guest process (ssh or git) → $SSH_AUTH_SOCK → Kasm SSH-agent bridge → KasmVNC relay → Kasm Native Smartcard Client → user's local SSH agent.

Git commit signing over SSH uses the same forwarded agent rather than a separate mechanism. Once $SSH_AUTH_SOCK points at the forwarded agent, git config gpg.format ssh and ssh-keygen -Y sign sign commits with the identities already loaded locally. Keys protected by a PIN trigger a native PIN-prompt dialog on the user's device.

Common troubleshooting steps​

Confirm the following before deeper diagnosis:

  • The allow_kasm_ssh_agent_passthrough Group Setting is set to true for one of the user's groups.
  • If the session came from a Session Casting configuration with Enforce Client Settings enabled, Allow Kasm SSH Agent Passthrough is enabled on that configuration.
  • The Kasm Native Smartcard Client is installed and running on the user's device.
  • The local SSH agent is running and has the intended keys loaded before the session launches.

If SSH-agent passthrough fails:

  1. Confirm the local agent socket or pipe exists on the user's device before the session launches.
  2. Inside the workspace, confirm $SSH_AUTH_SOCK is set and points to a live socket. Some desktop environments start their own local ssh-agent during session startup, which can overwrite $SSH_AUTH_SOCK for anything spawned afterward. If ssh-add -l reports no identities, open a new terminal in the session and check $SSH_AUTH_SOCK again.
  3. Confirm the application image did not overwrite the default shell profile during its own install steps. An image that replaces ~/.bashrc wholesale can drop the $SSH_AUTH_SOCK export along with it. If one specific application image never picks up the forwarded agent while others do, check whether that image's install scripts overwrite the default profile.