Why use SSM Session Client instead of the AWS CLI?

How it works

SSM Session Client uses the AWS SSM StartSession API to create an encrypted WebSocket tunnel to your EC2 instance via the SSM Messages service. All traffic flows through AWS — no inbound firewall rules, no bastion hosts, no VPN to the instances themselves.

Access is controlled by IAM policy, not by distributing SSH keys. You grant (or revoke) access to an instance with a policy change, and every session is logged by AWS CloudTrail.

In environments where only AWS PrivateLink endpoints are reachable (VPN or Direct Connect), the ssmmessages-endpoint flag replaces the public StreamUrl returned by StartSession with your private endpoint. This is the primary feature that makes SSM Session Client useful in air-gapped or restricted networks.

Built for restricted enterprise environments

In many enterprise environments, application whitelisting and endpoint security tools prevent users from installing or running the AWS CLI, Python, or the Session Manager plugin. SSM Session Client is a single, statically compiled Go binary with zero runtime dependencies — it runs anywhere a standard executable is allowed.

Tested and used in environments protected by:

• Microsoft AppLocker — the binary can be deployed to an approved path and whitelisted by publisher or hash rule
• Airlock Digital — approved as a single file, no additional libraries or interpreters to trust
• ManageEngine / Endpoint Central — no installer, no registry changes, no service dependencies
• CrowdStrike, Carbon Black, SentinelOne — no child processes to spawn (unlike the AWS CLI which invokes Python and the plugin)

Because it ships as one file with everything built in — SSH client, SSM data channel, WebSocket transport, SSO login — there is nothing extra to install, configure, or get approved by your security team. Copy the binary, set your AWS credentials, and connect.

This also makes SSM Session Client ideal for complex network environments where AWS service endpoints are only reachable via VPN or Direct Connect through AWS PrivateLink. The ssmmessages-endpoint flag lets you override the public StreamUrl with your private VPC endpoint, keeping all session traffic within your private network.

Install

SSM Session Client is a single binary with no runtime dependencies. Download the binary for your platform, make it executable, and add it to your PATH.

macOS

# Download the latest binary
curl -fsSL \
  https://github.com/alexbacchin/ssm-session-client/releases/latest/download/ssm-session-client-darwin-arm64 \
  -o /usr/local/bin/ssm-session-client

# Make it executable
chmod +x /usr/local/bin/ssm-session-client

# Verify
ssm-session-client --version

# Download the latest binary
curl -fsSL \
  https://github.com/alexbacchin/ssm-session-client/releases/latest/download/ssm-session-client-darwin-amd64 \
  -o /usr/local/bin/ssm-session-client

# Make it executable
chmod +x /usr/local/bin/ssm-session-client

# Verify
ssm-session-client --version

Linux

sudo curl -fsSL \
  https://github.com/alexbacchin/ssm-session-client/releases/latest/download/ssm-session-client-linux-amd64 \
  -o /usr/local/bin/ssm-session-client

sudo chmod +x /usr/local/bin/ssm-session-client

ssm-session-client --version

sudo curl -fsSL \
  https://github.com/alexbacchin/ssm-session-client/releases/latest/download/ssm-session-client-linux-arm64 \
  -o /usr/local/bin/ssm-session-client

sudo chmod +x /usr/local/bin/ssm-session-client

ssm-session-client --version

sudo curl -fsSL \
  https://github.com/alexbacchin/ssm-session-client/releases/latest/download/ssm-session-client-linux-386 \
  -o /usr/local/bin/ssm-session-client

sudo chmod +x /usr/local/bin/ssm-session-client

ssm-session-client --version

# For ARMv7 (Raspberry Pi 3/4, most modern ARM boards)
sudo curl -fsSL \
  https://github.com/alexbacchin/ssm-session-client/releases/latest/download/ssm-session-client-linux-arm7 \
  -o /usr/local/bin/ssm-session-client

# For ARMv6 (Raspberry Pi Zero/1)
# Replace "arm7" with "arm6" in the URL above

sudo chmod +x /usr/local/bin/ssm-session-client

ssm-session-client --version

Windows

# Download to a folder already on your PATH (e.g. C:\tools)
$url = "https://github.com/alexbacchin/ssm-session-client/releases/latest/download/ssm-session-client-windows-amd64.exe"
Invoke-WebRequest -Uri $url -OutFile "C:\tools\ssm-session-client.exe"

# Verify
ssm-session-client --version

$url = "https://github.com/alexbacchin/ssm-session-client/releases/latest/download/ssm-session-client-windows-arm64.exe"
Invoke-WebRequest -Uri $url -OutFile "C:\tools\ssm-session-client.exe"

ssm-session-client --version

Optional: AWS Session Manager Plugin

The AWS Session Manager Plugin is not required. ssm-session-client handles all SSM functionality natively, including KMS-encrypted sessions. No additional software is needed.

If the plugin is installed, ssm-session-client can optionally use it (controlled by the --ssm-session-plugin flag). Install instructions: Install the Session Manager plugin for the AWS CLI.

Code Signing Certificate

Windows binaries are signed with an Authenticode code signing certificate. This allows enterprise security tools to verify the publisher and integrity of the binary. The certificate details below can be used to create whitelisting rules in AppLocker, Airlock Digital, and other endpoint security products.

AppLocker — Publisher Rule

Create a publisher rule in your AppLocker EXE policy that allows binaries signed by this certificate. In Group Policy Editor:

1. Navigate to Computer Configuration → Windows Settings → Security Settings → Application Control Policies → AppLocker → Executable Rules
2. Right-click → Create New Rule → select Publisher
3. Browse to the signed ssm-session-client.exe binary
4. Set the slider to Publisher level to allow any binary signed by O=github.com/alexbacchin, CN=Alex Bacchin

Alternatively, use a File Hash rule with the SHA-256 hash of the specific release binary.

Airlock Digital

Add the binary by certificate fingerprint or file hash. Use the SHA-256 fingerprint above to create a trusted publisher rule, or add the specific binary hash from the release checksums file.

Verifying the Signature

On Windows, right-click the .exe → Properties → Digital Signatures tab to inspect the certificate. From PowerShell:

# View the Authenticode signature
Get-AuthenticodeSignature .\ssm-session-client.exe

# Detailed certificate info
(Get-AuthenticodeSignature .\ssm-session-client.exe).SignerCertificate | Format-List

Configuration

ssm-session-client reads its configuration from three sources, in order of precedence (highest first):

1. Command-line flags — highest priority, override everything
2. Environment variables — prefix SSC_ (e.g. SSC_AWS_REGION)
3. YAML config file — lowest priority, supplies defaults

AWS Credentials

ssm-session-client uses the standard AWS SDK credential chain. No special configuration is needed beyond what you would set up for the AWS CLI. Refer to the AWS documentation: Authentication and access credentials for the AWS CLI.

Common methods:

• Named profiles in ~/.aws/credentials and ~/.aws/config
• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
• EC2 instance metadata / ECS task role
• AWS Identity Center (SSO) — see SSO Login below

Configuration Options

Config File

The default config file path is $HOME/.ssm-session-client.yaml (Linux/macOS) or %USERPROFILE%\.ssm-session-client.yaml (Windows).

The file is searched in this order:

1. Current working directory
2. User home directory ($HOME / %USERPROFILE%)
3. Directory containing the ssm-session-client executable

Pass a custom path with --config=/path/to/config.yaml.

Minimal config (AWS profile + region)

aws-profile: my-profile
aws-region: ap-southeast-2

AWS Identity Center SSO Login

ssm-session-client can trigger an AWS SSO device-code login automatically before each session. This eliminates the need to run aws sso login separately.

1. Configure the AWS CLI for SSO. Follow the AWS guide: Configuring the AWS CLI to use AWS IAM Identity Center. This creates a profile section in ~/.aws/config with sso_start_url, sso_account_id, sso_role_name, and sso_region.
2. Set aws-profile and sso-login: true in your config file (or pass them as flags/env vars).
3. (Optional) Set sso-open-browser: true if your machine can open a browser. Otherwise, copy the verification URL printed to the terminal and open it in any browser.

SSO config file example

aws-profile: my-sso-profile
aws-region: ap-southeast-2
sso-login: true
sso-open-browser: true

VPC Endpoints (PrivateLink)

In environments where AWS services are only reachable via AWS PrivateLink (VPN or Direct Connect), you can override each service endpoint individually.

The ssmmessages-endpoint flag is the critical one: the StartSession API always returns a public StreamUrl. This flag replaces that URL with your private VPC endpoint so the WebSocket tunnel stays entirely within your private network.

Config file with VPC endpoint overrides

aws-profile: sandbox
aws-region: us-west-2

# VPC endpoint DNS names (from your VPC endpoint console/outputs)
ec2-endpoint:          vpce-059c3b85db66f8165-mzb6o9nb.ec2.us-west-2.vpce.amazonaws.com
ssm-endpoint:          vpce-06ef6f173680a1306-bt58rzff.ssm.us-west-2.vpce.amazonaws.com
ssmmessages-endpoint:  vpce-0e5e5b0c558a14bf2-r3p6zkdm.ssmmessages.us-west-2.vpce.amazonaws.com
sts-endpoint:          vpce-0877b4abeb479ee06-arkdktlc.sts.us-west-2.vpce.amazonaws.com

# Optional: HTTP proxy for services without a custom endpoint set
proxy-url: http://myproxy:3128

Target Lookup

All session commands accept a target as the first argument. Targets are resolved using the following chain (first match wins):

Target Aliases

Aliases map a short friendly name to an EC2 tag key + value. They are unique — the lookup errors if more than one running instance matches, so the alias always refers to exactly one host.

Define aliases in the config file

aliases:
  devbox:
    tag-name: Name
    tag-value: my-devbox
  prod-web:
    tag-name: Environment
    tag-value: production

Define aliases on the command line (repeatable)

# Single alias on the fly
ssm-session-client shell devbox --alias devbox=Name:my-devbox

# Multiple aliases
ssm-session-client shell prod-web \
  --alias devbox=Name:my-devbox \
  --alias prod-web=Environment:production

CLI aliases override same-named aliases in the config file. Use aliases with any command:

ssm-session-client shell            devbox
ssm-session-client ssh-direct       ec2-user@devbox
ssm-session-client port-forwarding  devbox:443 8443

Automatic Reconnection

ssm-session-client automatically reconnects when a WebSocket connection drops. Configure it with:

• --enable-reconnect — enable/disable (default: true)
• --max-reconnects — maximum attempts before giving up (default: 5, set 0 for unlimited)

Data Channel Encryption

When KMS encryption is enabled for SSM sessions, the data channel is encrypted using AES-256-GCM. Encryption keys are derived from AWS KMS using the GenerateDataKey API, with the session ID and target ID as encryption context.

SSM Session Client has built-in support for KMS-encrypted sessions and does not require the AWS Session Manager plugin. The encryption is handled natively using Go's crypto libraries. If the Session Manager plugin is installed and enabled (ssm-session-plugin: true), it will be used instead, but it is not required.

Session Modes

Shell

Opens an interactive terminal session on the target instance. Equivalent to aws ssm start-session.

ssm-session-client shell i-0bdb4f892de4bb54c
ssm-session-client shell i-0bdb4f892de4bb54c --config=~/.ssm-session-client.yaml

On Windows, the shell command supports virtual terminal processing with ANSI escape sequences for proper colour and formatting in remote shells.

IAM reference: Sample IAM policies for Session Manager

SSH (ProxyCommand)

Uses ssm-session-client as an SSH ProxyCommand, forwarding stdio to the SSM data channel. The SSH client (system ssh) handles authentication and encryption. Requires an SSH server on the target instance.

1. Configure SSH

Add to ~/.ssh/config (Linux/macOS) or %USERPROFILE%\.ssh\config (Windows):

Host i-* mi-*
  ProxyCommand ssm-session-client ssh %r@%h --config=~/.ssm-session-client.yaml

2. Automatically configure SSH (optional)

ssm-session-client ssh add-proxy-command ec2-user@i-0bdb4f892de4bb54c

3. Connect

ssh ec2-user@i-0bdb4f892de4bb54c

IAM reference: Enabling SSH connections through Session Manager

SSH Direct (Native SSH Client)

A fully integrated SSH session over SSM using Go's native SSH library. No external SSH client, no ProxyCommand, no SSH server listening on an open port.

# Interactive session
ssm-session-client ssh-direct ec2-user@i-0123456789abcdef0

# With a specific key file
ssm-session-client ssh-direct ec2-user@i-0123456789abcdef0 --ssh-key ~/.ssh/my-key

# Run a single command
ssm-session-client ssh-direct ec2-user@i-0123456789abcdef0 --exec "uptime"

# Using EC2 Instance Connect (no SSH key management needed)
ssm-session-client ssh-direct ec2-user@i-0123456789abcdef0 --instance-connect

# Custom SSH port
ssm-session-client ssh-direct ec2-user@i-0123456789abcdef0:2222

Authentication chain (tried in order)

1. Ephemeral key via EC2 Instance Connect (when --instance-connect is used)
2. SSH agent (SSH_AUTH_SOCK)
3. Private key file (--ssh-key or auto-discovered ~/.ssh/id_ed25519 / ~/.ssh/id_rsa)
4. Password prompt (interactive)

Config file example

ssh-direct options live under the ssh-direct: section in the config file:

ssh-direct:
  ssh-key-file: ~/.ssh/id_ed25519   # private key (omit to auto-discover)
  no-host-key-check: false          # set true only in trusted environments
  instance-connect: true            # push ephemeral key via EC2 Instance Connect

VSCode Remote SSH Integration

ssm-session-client can act as the SSH executable for VSCode Remote SSH, eliminating the need for an external SSH client or ProxyCommand setup. This is especially useful on Windows where OpenSSH may not be installed.

1. Configure the binary path in VSCode. Open Settings (Ctrl+,) and search for remote.SSH.path, or add to settings.json:

   // Linux / macOS
   { "remote.SSH.path": "/usr/local/bin/ssm-session-client" }
   
   // Windows
   { "remote.SSH.path": "C:\\tools\\ssm-session-client.exe" }

2. Configure your SSH config file (~/.ssh/config or %USERPROFILE%\.ssh\config):

   # A named host mapped to an instance ID
   Host my-server
     HostName i-0123456789abcdef0
     User ec2-user
   
   # Wildcard for all instance IDs
   Host i-*
     User ec2-user
     StrictHostKeyChecking accept-new

3. Set AWS credentials. Use a config file, environment variables (AWS_PROFILE, AWS_REGION), or the standard credential chain. The ssm-session-client config file is also honoured for VPC endpoint overrides.
4. Connect. In VSCode, open the Command Palette (Ctrl+Shift+P) → Remote-SSH: Connect to Host… → select your configured host.

Supported SSH Flags

When operating in OpenSSH-compat mode (VSCode or symlink), the following SSH flags are recognised:

SSH with EC2 Instance Connect

The instance-connect command combines SSM session tunnelling with EC2 Instance Connect. It pushes an ephemeral SSH public key to the instance before connecting, so no permanent key management is needed. Authentication is controlled by the IAM action ec2-instance-connect:SendSSHPublicKey.

# SSH config using instance-connect as ProxyCommand
Host i-*
  ProxyCommand ssm-session-client instance-connect %r@%h

# With a custom key pair
Host i-*
  IdentityFile ~/.ssh/custom
  ProxyCommand ssm-session-client instance-connect %r@%h --ssh-public-key-file=~/.ssh/custom.pub

# Automatically configure SSH
ssm-session-client instance-connect add-proxy-command ec2-user@i-0bdb4f892de4bb54c

# Then connect normally
ssh ec2-user@i-0bdb4f892de4bb54c

Port Forwarding

Securely tunnel TCP traffic to a port on a private instance without SSH, open firewall rules, or a bastion host.

# Forward local port 8888 → instance port 443
ssm-session-client port-forwarding i-0bdb4f892de4bb54c:443 8888

# Auto-assign local port
ssm-session-client port-forwarding i-0bdb4f892de4bb54c:443

RDP (Windows targets only)

The rdp command (Windows build only) sets up a port-forwarding tunnel to port 3389 and launches mstsc.exe automatically.

# Basic RDP connection
ssm-session-client rdp i-0bdb4f892de4bb54c

# Retrieve the Windows administrator password automatically
ssm-session-client rdp i-0bdb4f892de4bb54c --get-password --key-pair-file ~/.ssh/my-ec2-keypair.pem

# Custom RDP port and username
ssm-session-client rdp i-0bdb4f892de4bb54c --rdp-port 3390 --username admin

When --get-password is used, the password is retrieved from the EC2 API, decrypted with the provided key pair, and copied to the clipboard for pasting into the RDP credentials prompt.

IAM: requires ec2:GetPasswordData in addition to standard SSM session permissions.

Troubleshooting

Log Files

Logs are written to both the console and a rotating log file. The log directory depends on your operating system:

Log files are rotated daily or when they reach 10 MB. The last three log files are kept.

Debug Mode

Set the log level to debug to capture verbose output including AWS API calls, WebSocket messages, and connection lifecycle events.

Via environment variable (recommended for quick debugging)

SSC_LOG_LEVEL=debug ssm-session-client shell i-0bdb4f892de4bb54c

Via config file

log-level: debug

Via CLI flag

ssm-session-client shell i-0bdb4f892de4bb54c --log-level=debug

Common Issues

macOS: "ssm-session-client cannot be opened"

macOS Gatekeeper quarantines downloaded binaries. Remove the quarantine flag:

xattr -d com.apple.quarantine /usr/local/bin/ssm-session-client

Windows: SmartScreen warning

Click More info → Run anyway. The binary is code-signed; SmartScreen may still warn on first run until the binary has sufficient reputation. Running from an Administrator PowerShell session bypasses this.

Connection times out / "target not connected"

• Verify the SSM Agent is running on the instance: in the EC2 console, check Systems Manager → Fleet Manager → instance status.
• Ensure the instance has the required IAM instance profile with the AmazonSSMManagedInstanceCore managed policy.
• If using VPC endpoints, confirm all four endpoints (ssm, ssmmessages, ec2, sts) are in place and their security groups allow traffic from the instance.
• Enable debug logging (see above) and check the log file for API error details.

SSO: "no valid SSO token found"

• Ensure sso-login: true is set in your config (or --sso-login flag).
• If you cannot open a browser, copy the verification URL from the debug log or console and open it on another device.
• Verify the SSO profile in ~/.aws/config has sso_start_url, sso_account_id, sso_role_name, and sso_region.

Target not found

• Confirm the EC2 instance is in a running state.
• For tag-based lookup, ensure the IAM credentials have ec2:DescribeInstances.
• For alias lookup, confirm the alias is defined in the config file or passed with --alias.

Contributing

Contributions are welcome! Please open an issue to discuss significant changes before submitting a pull request. All code must pass the lint and unit tests before merging.

Prerequisites

• Go (version from go.mod)
• golangci-lint for linting
• Acceptance tests only: An AWS account, and OpenTofu (or Terraform) for provisioning test infrastructure

Building from Source

# Clone the repository
git clone https://github.com/alexbacchin/ssm-session-client.git
cd ssm-session-client

# Build for the current platform
go build -o ssm-session-client .

# Cross-compile
GOOS=linux   GOARCH=amd64 go build -o ssm-session-client-linux-amd64 .
GOOS=darwin  GOARCH=arm64 go build -o ssm-session-client-darwin-arm64 .
GOOS=windows GOARCH=amd64 go build -o ssm-session-client.exe .

Unit Tests

# Run all unit tests with the race detector and coverage
go test ./... -race -coverprofile=coverage.out -covermode=atomic

# View coverage summary
go tool cover -func=coverage.out

# Run a single test
go test ./ssmclient/... -run TestTargetResolver -race

Linting

golangci-lint run

Key lint constraints enforced in this project:

• Maximum function length: 75 lines / 50 statements
• Maximum cognitive/cyclomatic complexity: 15
• Maximum line length: 132 characters
• Active linters: errcheck, gosec, funlen, gocognit, gocyclo, revive, bodyclose

Acceptance Tests

The acceptance test suite provisions real AWS infrastructure (an EC2 instance with no inbound SSH access), runs end-to-end tests against it, and tears everything down. Tests are tagged acceptance and are excluded from the standard go test ./... run.

What the tests cover

• Shell access by instance ID, tag, alias, private IP, and DNS TXT record
• SSH direct and SSH proxy connections
• EC2 Instance Connect session
• Port forwarding (single and multiple concurrent connections)
• RDP tunnel (Windows runner, optional)
• SSO login with cached token (optional, requires an SSO profile)
• Error conditions: invalid target, missing region, session termination

1. Configure AWS credentials

The tests use standard AWS SDK credential chain. For CI, OIDC is recommended. For local runs, use a named profile or environment variables. The IAM principal needs permissions to manage EC2, SSM, IAM roles, and (optionally) Route53, KMS.

2. Provision infrastructure

cd test/scripts
make acceptance-prepare AWS_REGION=ap-southeast-2

# Wait for the SSM agent to come online
make acceptance-wait-ssm AWS_REGION=ap-southeast-2

3. Run the tests

make acceptance-run-local

4. Tear down

make acceptance-destroy AWS_REGION=ap-southeast-2

Full lifecycle (provision → test → destroy)

make acceptance AWS_REGION=ap-southeast-2

Interactive SSO test

# Requires a human to approve the device code in a browser
make acceptance-sso-interactive SSO_PROFILE=my-sso-profile

Windows / RDP tests

# Provision with a Windows instance
make acceptance-prepare TF_EXTRA_VARS="-var=create_windows_instance=true"

# Run on a Windows runner with the acceptance+windows build tags
go test ./test/acceptance/... -tags "acceptance windows" -run RDP -v