SSH Access

Overview

PyBritive supports three approaches for SSH access to remote servers. The right approach depends on your network setup and cloud infrastructure.

Approach	When to use
Resources SSH key injection	Instance is reachable via public IP or VPN. PyBritive checks out a temporary SSH key automatically before each connection.
AWS Session Manager	EC2 instance has no public IP and port 22 is closed. SSH tunnels through AWS Systems Manager — no VPN or firewall changes needed.
GCP Identity Aware Proxy	GCP Compute Engine instance has no public IP. SSH tunnels through Google Cloud IAP — no open firewall port needed.

What you’ll learn:

How to configure automatic SSH key injection using PyBritive Resources profiles
How to connect to private AWS EC2 instances via Session Manager
How to connect to private GCP Compute Engine instances via IAP

Before You Begin

For Resources SSH key injection:

PyBritive installed and authenticated — see Getting Started
A Britive Resources SSH profile available for checkout — see Listing Your Access
OpenSSH installed — run ssh -V to check
Instance reachable via public IP or VPN

For AWS Session Manager:

AWS CLI installed with the Session Manager plugin
EC2 instance with the Systems Manager agent and EC2 Instance Connect agent installed
OpenSSH installed

For GCP Identity Aware Proxy:

gcloud CLI installed — run gcloud --version to check
GCP profile checked out and authenticated — see GCP Credentials
Compute Engine instance accepting SSH keys via OS Login or instance metadata
OpenSSH installed

Resources SSH Key Injection

This approach uses a Britive Resources profile to check out a temporary SSH private key before each connection. OpenSSH’s Match exec directive triggers the checkout automatically — you just run ssh as normal.

Identify your Resources SSH profile

List your available profiles and look for Resources type profiles:

pybritive ls profiles --format table

Resources SSH profiles appear with type Resources. Note the full profile name — for example:

resources/linux-demo02/no sudo ssh access

Create a profile alias

Create an alias for the profile to simplify the SSH config:

pybritive checkout "resources/linux-demo02/no sudo ssh access" --alias dev-server02

Configure ~/.ssh/config

Add the following to your ~/.ssh/config, replacing the hostname, username, and alias with your own values:

Host dev-server02
    HostName ec2-35-89-23-250.us-west-2.compute.amazonaws.com
    User yourname
    IdentityFile /Users/yourname/.ssh/profiles/dev-server02.pem

Match Host dev-server02*,ec2-35-89-23-250* exec "pybritive checkout dev-server02 -t demo -s > /Users/yourname/.ssh/profiles/dev-server02.pem && chmod 600 /Users/yourname/.ssh/profiles/dev-server02.pem"

The Match exec block runs pybritive checkout before every SSH connection, writes the temporary private key to a PEM file, and sets the correct permissions. The -s flag runs checkout in silent mode so it doesn’t interrupt the SSH connection.

Create the directory for your key files if it doesn’t exist:

mkdir -p ~/.ssh/profiles

Connect

ssh dev-server02

PyBritive checks out a fresh key automatically before connecting. No manual checkout step is needed.

AWS EC2 via Session Manager

Session Manager creates a secure tunnel to your EC2 instance through AWS Systems Manager. The instance needs no public IP and port 22 does not need to be open.

Generate your SSH config

PyBritive can generate the OpenSSH Match directives needed to route connections through Session Manager:

pybritive ssh aws config

Add the output to your ~/.ssh/config file.

Connect using Session Manager only

Connect to an instance using its EC2 instance ID:

ssh i-1234567890abcdef0

To target a specific AWS profile and region:

ssh i-1234567890abcdef0.my-aws-profile.us-east-1

Connect with ephemeral key injection

Use EC2 Instance Connect to inject a one-time ephemeral key into the instance before connecting:

pybritive ssh aws ssm-proxy --hostname i-1234567890abcdef0 \
  --username ec2-user \
  --push-public-key

To store the private key using ssh-agent:

pybritive ssh aws ssm-proxy --hostname i-1234567890abcdef0 \
  --username ec2-user \
  --push-public-key \
  --key-source ssh-agent

GCP Compute Engine via IAP

Identity Aware Proxy (IAP) is Google Cloud’s authentication gateway for private instances. Instead of opening a firewall port, IAP verifies your identity and forwards the connection only if authorized.

Generate your SSH config

Generate the OpenSSH Match directives for GCP IAP tunneling:

pybritive ssh gcp config

Add the output to your ~/.ssh/config file.

Connect using IAP only

GCP hostnames follow the format gcp.<instance-name>.<project-id>:

ssh gcp.my-instance.my-project-id

Connect with ephemeral key injection

Use OS Login to inject a one-time ephemeral key before connecting:

pybritive ssh gcp identity-aware-proxy \
  --hostname gcp.my-instance.my-project-id \
  --username my-username \
  --push-public-key \
  --key-source ssh-agent

Troubleshoot

Symptom	Cause	Fix
`Permission denied (publickey)` on Resources approach	PEM file not written or wrong permissions	Confirm the `Match exec` command ran successfully and `chmod 600` was applied
SSH connects but immediately drops	Temporary key expired	The `Match exec` block refreshes the key on each connection — retry the SSH command
`session-manager-plugin: command not found`	SSM plugin not installed	Install the AWS Session Manager plugin
`Connection refused` on EC2	Systems Manager agent not running on instance	Confirm SSM agent is installed and running on the instance
IAP tunnel opens but SSH fails on GCP	OS Login two-factor authentication enabled	Disable 2FA for OS Login or use instance metadata key injection instead
`gcloud: command not found`	gcloud CLI not installed	Install the Google Cloud CLI

Next Steps

Shell Completion — set up tab completion for PyBritive commands in your shell

Last updated on July 8, 2026

Approval Workflows Shell Completion