Connection Flow

Connection Flow

Understanding how cloudX-proxy establishes connections helps with troubleshooting and explains why certain configurations and timeouts are necessary.

Overview

cloudX-proxy uses a sophisticated multi-step process to establish secure connections between your local VSCode and EC2 instances through AWS Systems Manager, without requiring direct SSH access or public IP addresses.

Step-by-Step Connection Process

1. VSCode Initiates SSH Connection

VSCode → SSH Client → SSH Config → ProxyCommand → cloudX-proxy

What happens:

• User clicks "Connect" in VSCode or runs ssh cloudx-{env}-{hostname}
• SSH client reads configuration from ~/.ssh/vscode/config
• SSH finds matching host configuration
• SSH calls cloudX-proxy as ProxyCommand with instance parameters

Key Configuration:

Host cloudx-dev-myserver
    HostName i-0123456789abcdef0
    ProxyCommand uvx cloudx-proxy connect %h %p --profile myprofile --ssh-key mykey

2. AWS Authentication & Instance Check

cloudX-proxy → AWS STS → EC2 API → SSM API

What happens:

• cloudX-proxy authenticates using specified AWS profile
• Verifies caller identity and permissions
• Checks if target EC2 instance exists and is accessible
• Queries instance state (running, stopped, etc.)
• Verifies SSM agent is installed and running on instance

AWS APIs Used:

• sts:GetCallerIdentity - Verify authentication
• ec2:DescribeInstances - Check instance existence and state
• ssm:DescribeInstanceInformation - Verify SSM connectivity

3. Instance Startup (if needed)

cloudX-proxy → EC2 StartInstances → Wait for Running State → SSM Connectivity Check

What happens:

• If instance is stopped, cloudX-proxy starts it automatically
• Waits for instance to reach "running" state
• Monitors SSM connectivity until agent responds
• This step can take 30-90 seconds depending on instance type

Timing Factors:

• t3.micro: ~30-45 seconds
• t3.medium: ~45-60 seconds
• Larger instances: 60-90 seconds
• First boot after AMI: Additional 1-2 minutes

4. SSH Key Distribution

cloudX-proxy → Read Public Key → EC2 Instance Connect → Temporary Authorization

What happens:

• Reads public SSH key from local filesystem (~/.ssh/vscode/mykey.pub)
• Uses EC2 Instance Connect to push public key to instance
• Key is temporarily authorized for 60 seconds
• Target user is ec2-user (configurable)

Security Note:

• Keys are injected temporarily and automatically expire
• No permanent key storage on the instance
• Each connection gets fresh key authorization

5. SSM Tunnel Establishment

cloudX-proxy → SSM StartSession → Port Forward → Local Tunnel

What happens:

• Creates secure tunnel through AWS Systems Manager
• Port forwards from local random port to instance port 22
• All traffic encrypted end-to-end through AWS
• No inbound ports needed on instance

Tunnel Properties:

• Protocol: AWS SSM Session Manager protocol over HTTPS
• Encryption: TLS 1.2+ end-to-end
• Port Forward: Local ephemeral port → Instance:22
• Network Path: Client → AWS API → SSM Service → Instance

6. SSH Connection Completion

SSH Client → Local Tunnel → SSM → Instance SSH Daemon → Authentication

What happens:

• SSH client connects through established tunnel
• Authenticates using private SSH key
• SSH session established with ec2-user
• VSCode completes remote connection setup

Connection Timeline

First Connection (Cold Start)

0:00 - VSCode initiates connection
0:01 - cloudX-proxy starts, authenticates AWS
0:02 - Instance startup begins (if stopped)
0:45 - Instance reaches running state
1:00 - SSM connectivity established
1:05 - SSH key pushed via Instance Connect
1:10 - SSM tunnel created
1:15 - SSH authentication complete
1:20 - VSCode server installation begins
3:30 - Connection ready for use

Subsequent Connections (Warm Start)

0:00 - VSCode initiates connection
0:01 - cloudX-proxy starts, authenticates AWS
0:02 - Instance already running, SSM ready
0:05 - SSH key pushed via Instance Connect
0:08 - SSM tunnel created (reuses existing)
0:10 - SSH authentication complete
0:30 - Connection ready (VSCode server already installed)

Connection Indicators

cloudX-proxy Messages

• "Authenticating with AWS..." - Verifying credentials and permissions
• "Starting instance i-123..." - EC2 instance being started from stopped state
• "Instance starting up..." - Waiting for running state
• "Waiting for SSM connectivity..." - Instance booting, SSM agent not ready
• "Pushing SSH key..." - Distributing public key via EC2 Instance Connect
• "Starting session..." - Creating SSM tunnel
• "Port forwarding established" - Tunnel ready for SSH

VSCode Messages

• "Connecting to host..." - SSH connection attempt
• "Installing server..." - First-time VSCode server download and setup
• "Starting server..." - VSCode server launching
• "Connected" - Ready for development

Why Timeouts Are Important

Connection Timeout (90s)

Accounts for:

• AWS API authentication (1-2s)
• Instance startup if stopped (30-90s)
• SSM connectivity wait (10-30s)
• SSH key distribution (1-3s)
• Tunnel establishment (1-5s)

Server Install Timeout (120s)

Accounts for:

• VSCode server download (30-60s)
• Server installation (30-60s)
• Initial server startup (10-30s)
• Network conditions and retries

SSH Keep-Alive Settings

TCPKeepAlive yes
ControlMaster auto
ControlPath ~/.ssh/control/%r@%h:%p
ControlPersist 4h

• TCPKeepAlive: Prevents connection drops during idle periods
• ControlMaster: Reuses SSH connections for better performance
• ControlPersist: Keeps master connection open for 4 hours

Connection Optimization

SSH Multiplexing

Multiple SSH sessions (terminal, file transfer, port forwarding) share a single underlying connection:

VSCode Terminal ──┐
VSCode Files    ──┼── SSH Master Connection ── SSM Tunnel ── Instance
Port Forwards   ──┘

Connection Reuse

• SSM tunnels can be reused across SSH sessions
• SSH master connections persist for configured duration
• Subsequent connections are much faster (30s vs 3m)

Troubleshooting Connection Flow

Step 1 Failures (SSH Config)

• "Host not found": Check SSH configuration
• "Permission denied (publickey)": Check SSH key permissions
• "ProxyCommand failed": Check cloudX-proxy installation

Step 2 Failures (AWS Auth)

• "Access denied": Check AWS credentials and permissions
• "Region not found": Verify AWS profile region configuration
• "Instance not found": Check instance ID and region

Step 3 Failures (Instance Startup)

• Timeout waiting for running: Instance may have startup issues
• SSM agent not responding: Check SSM agent installation and IAM role

Step 4 Failures (SSH Key)

• Key push failed: Check EC2 Instance Connect permissions
• Authentication failed: Check SSH key format and permissions

Step 5 Failures (SSM Tunnel)

• Session start failed: Check SSM permissions and Session Manager plugin
• Tunnel establishment timeout: Network connectivity issues

Step 6 Failures (SSH Auth)

• Permission denied: SSH key authentication problems
• Connection refused: SSH daemon not running or blocked

---

For specific error solutions, see the Troubleshooting Guide.