Skip to content

Quick Start

Jump to bottom
Erik Meinders edited this page Sep 9, 2025 · 1 revision

Quick Start

TL;DR for experienced users who want to get up and running quickly.

Prerequisites Check

Ensure you have:

  • ✅ Python 3.9+
  • ✅ AWS CLI v2 configured with profile
  • ✅ Session Manager plugin installed
  • ✅ VSCode with Remote SSH extension
  • ✅ EC2 instance(s) to connect to
# Quick verification
python --version && aws --version && uvx --version

4-Step Setup

1. Install Prerequisites

# Install uv if not already installed
pip install uv

2. Run cloudX-proxy Setup

# Interactive setup (recommended for first time)
uvx cloudx-proxy setup

# Non-interactive with all parameters
uvx cloudx-proxy setup --profile myprofile --instance i-1234567890abcdef0 --hostname myserver --yes

What this does:

  • Validates your AWS profile and permissions
  • Creates SSH key pair (or uses existing)
  • Configures SSH with three-tier structure
  • Sets up VSCode-compatible SSH configuration

3. Configure VSCode

Add to your VSCode settings.json:

{
    "remote.SSH.configFile": "~/.ssh/vscode/config",
    "remote.SSH.connectTimeout": 90,
    "remote.SSH.serverInstallTimeout": 120
}

4. Connect

  1. Open VSCode Remote Explorer → SSH Targets
  2. Find your host: cloudx-{env}-{hostname} (e.g., cloudx-dev-myserver)
  3. Click Connect

Common Quick Setup Patterns

Basic Setup with Defaults

uvx cloudx-proxy setup
# Uses 'vscode' profile and creates ~/.ssh/vscode/config

Custom Profile and Key

uvx cloudx-proxy setup --profile production --ssh-key prod-key

With 1Password Integration

uvx cloudx-proxy setup --1password
# Creates keys in 1Password vault, uses SSH agent

Multiple Instances, Same Environment

# First instance
uvx cloudx-proxy setup --profile dev --instance i-111111 --hostname web-server

# Second instance (reuses environment config)
uvx cloudx-proxy setup --profile dev --instance i-222222 --hostname db-server

Production Environment

uvx cloudx-proxy setup --profile prod --ssh-key prod --aws-env production --1password Work --yes

Expected Timings

  • First connection: 2-3 minutes (instance startup + VSCode server install)
  • Subsequent connections: ~30 seconds
  • Setup process: 2-5 minutes depending on options

Quick Troubleshooting

Connection Issues

# Check configuration
uvx cloudx-proxy list --detailed

# Test direct connection
uvx cloudx-proxy connect i-1234567890abcdef0 22 --profile myprofile

# Verify AWS access
aws sts get-caller-identity --profile myprofile

VSCode Issues

  • Increase timeouts if connections are slow
  • Check remote.SSH.configFile path is correct
  • Enable remote.SSH.showLoginTerminal for debugging

AWS Issues

  • Ensure instance has SSM agent running
  • Check IAM permissions for SSM and EC2 Instance Connect
  • Verify region matches between profile and instance

Advanced Quick Setup

Custom SSH Config Location

uvx cloudx-proxy setup --ssh-config ~/.ssh/company/config
# Update VSCode configFile accordingly

AWS Profile Organizer

uvx cloudx-proxy setup --aws-env staging
# Uses ~/.aws/aws-envs/staging/ for credentials

Non-Interactive CI/CD

uvx cloudx-proxy setup \
  --profile ci-runner \
  --ssh-key deploy-key \
  --instance i-1234567890abcdef0 \
  --hostname prod-api \
  --yes

What Gets Created

After setup, you'll have:

~/.ssh/vscode/
├── config              # SSH configuration file
├── vscode              # Private SSH key (if not using 1Password)
└── vscode.pub         # Public SSH key

~/.ssh/config          # Updated to include vscode config

SSH Configuration Structure:

  • Generic: cloudx-* (common settings)
  • Environment: cloudx-{env}-* (auth, proxy command)
  • Host: cloudx-{env}-hostname (specific instance)

Next Steps

For detailed explanations, see the Installation Guide and Setup Command pages.

Clone this wiki locally