cloudx-proxy 0.8.2__tar.gz → 0.8.3__tar.gz

{cloudx_proxy-0.8.2 → cloudx_proxy-0.8.3}/CHANGELOG.md

@@ -1,3 +1,5 @@
+## [0.8.3](https://github.com/easytocloud/cloudX-proxy/compare/v0.8.2...v0.8.3) (2025-09-09)
+
 ## [0.8.2](https://github.com/easytocloud/cloudX-proxy/compare/v0.8.1...v0.8.2) (2025-09-09)
 
 

{cloudx_proxy-0.8.2 → cloudx_proxy-0.8.3}/CLAUDE.md

@@ -88,11 +88,41 @@ Commit message format affects version bumps:
 
 ### 1Password Integration
 
-When `--1password` is used:
-- Checks for existing SSH keys in any 1Password vault
-- Creates new keys in user-selected vault if needed
-- Configures SSH to use 1Password SSH agent (`IdentityAgent ~/.1password/agent.sock`)
-- Uses public key file to limit SSH agent key search (`IdentitiesOnly yes`)
+The `--1password` flag enables comprehensive SSH key management through 1Password's secure vault system and SSH agent. This integration provides a complete workflow for creating, managing, and using SSH keys without exposing private keys to the filesystem.
+
+#### Prerequisites
+- 1Password CLI installed and available in PATH
+- User authenticated to 1Password (`op account list` succeeds)
+- 1Password SSH agent enabled and running (`~/.1password/agent.sock` exists)
+
+#### Key Discovery and Management Workflow
+1. **Existing Key Search**: Searches all 1Password vaults for SSH keys matching the specified name
+2. **Key Naming Convention**: Uses consistent naming with prefix "cloudX SSH Key - {keyname}"
+3. **Vault Selection**: 
+   - If vault specified via `--1password VaultName`, uses that vault
+   - If specified vault not found, prompts user to select from available vaults
+   - In interactive mode, displays all available vaults for selection
+4. **Key Creation**: Creates new SSH key pair directly in 1Password vault if no existing key found
+5. **Public Key Export**: Exports public key to filesystem at expected SSH config location
+
+#### SSH Configuration Generated
+When using 1Password integration, the SSH configuration includes:
+- `IdentityAgent ~/.1password/agent.sock` - Points to 1Password SSH agent
+- `IdentityFile {keyfile}.pub` - References public key file to limit key search
+- `IdentitiesOnly yes` - Prevents SSH from trying other keys in agent
+
+#### Error Handling and Fallbacks
+- If 1Password CLI unavailable: Prompts user to continue with standard SSH key setup
+- If authentication fails: Provides setup instructions and troubleshooting guidance  
+- If key creation fails: Falls back to standard SSH key generation
+- If SSH agent unavailable: Warns user and provides configuration guidance
+
+#### Security Benefits
+- Private keys never touch the filesystem
+- Centralized key management across devices
+- Audit trail through 1Password logging
+- Automatic key rotation capabilities
+- Integration with 1Password's biometric authentication
 
 ### AWS Environment Support
 

{cloudx_proxy-0.8.2 → cloudx_proxy-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudx-proxy
-Version: 0.8.2
+Version: 0.8.3
 Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
 Author-email: easytocloud <info@easytocloud.com>
 License: MIT License
@@ -73,25 +73,62 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
 - SSH tunneling through AWS Systems Manager
 - Cross-platform support (Windows, macOS, Linux)
 
+## Quick Start
+
+**TL;DR for experienced users:**
+
+1. **Install Prerequisites:**
+   ```bash
+   # Install Python 3.9+, AWS CLI v2, Session Manager plugin
+   pip install uv
+   ```
+
+2. **Run Setup:**
+   ```bash
+   # Basic setup (will prompt for AWS profile, instance ID, etc.)
+   uvx cloudx-proxy setup
+   
+   # Or non-interactive with all parameters
+   uvx cloudx-proxy setup --profile myprofile --instance i-1234567890abcdef0 --hostname myserver --yes
+   ```
+
+3. **Configure VSCode:**
+   - Install "Remote - SSH" extension
+   - Add to settings.json: `"remote.SSH.configFile": "~/.ssh/vscode/config"`
+   - Set SSH timeout: `"remote.SSH.connectTimeout": 90`
+
+4. **Connect:**
+   - Open VSCode Remote Explorer → SSH Targets
+   - Connect to `cloudx-{env}-{hostname}` (e.g., `cloudx-dev-myserver`)
+
+**First connection takes 2-3 minutes (instance startup + VSCode server install). Subsequent connections are much faster (~30s).**
+
+---
+
 ## Prerequisites
 
-1. **AWS CLI v2** - Used to configure AWS profiles and credentials
+1. **Python 3.9+** - Required for cloudX-proxy and uv package manager
+   - [Python Installation Guide](https://www.python.org/downloads/)
+   - Check your version: `python --version` or `python3 --version`
+   - Supports Python 3.9, 3.10, 3.11, 3.12+
+
+2. **AWS CLI v2** - Used to configure AWS profiles and credentials
    - [Installation Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
    - Required for `aws configure` during setup
    - Handles AWS credentials and region configuration
 
-2. **AWS Session Manager Plugin** - Enables secure tunneling through AWS Systems Manager
+3. **AWS Session Manager Plugin** - Enables secure tunneling through AWS Systems Manager
    - [Installation Guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
    - Provides the secure connection channel
    - No need for public IP addresses or direct SSH access
 
-3. **OpenSSH Client** - Handles SSH key management and connections
+4. **OpenSSH Client** - Handles SSH key management and connections
    - Windows: [Microsoft's OpenSSH Installation Guide](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui)
    - macOS/Linux: Usually pre-installed
    - Manages SSH keys and configurations
    - Provides the SSH client for VSCode Remote
 
-4. **uv** - Modern Python package installer and virtual environment manager
+5. **uv** - Modern Python package installer and virtual environment manager
    ```bash
    pip install uv
    ```
@@ -102,7 +139,7 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
    
    This means you can run cloudX-proxy directly with `uvx cloudx-proxy` without manually managing virtual environments or dependencies.
 
-5. **VSCode with Remote SSH Extension** - Your development environment
+6. **VSCode with Remote SSH Extension** - Your development environment
    - Provides the integrated development environment
    - Uses the SSH configuration to connect to instances
    - Handles file synchronization and terminal sessions
@@ -265,15 +302,91 @@ This architecture means that:
 
 ### VSCode Configuration
 
-1. Install the "Remote - SSH" extension in VSCode
-2. Configure VSCode settings:
+After completing the setup, configure VSCode to use the SSH configuration created by cloudX-proxy:
+
+1. **Install VSCode Extensions:**
+   - Install the "Remote - SSH" extension from the VSCode marketplace
+   - Optionally install "Remote Explorer" for better visualization
+
+2. **Configure VSCode Settings:**
+   Add these settings to your VSCode settings.json (Command Palette → "Preferences: Open Settings (JSON)"):
    ```json
    {
        "remote.SSH.configFile": "~/.ssh/vscode/config",
-       "remote.SSH.connectTimeout": 90
+       "remote.SSH.connectTimeout": 90,
+       "remote.SSH.serverInstallTimeout": 120,
+       "remote.SSH.showLoginTerminal": true,
+       "remote.SSH.remotePlatform": {
+           "cloudx-*": "linux"
+       }
    }
    ```
-This extra long timeout is necessary to account for the time it takes to start the instance and establish the connection.
+
+3. **Configuration Explanations:**
+   - `configFile`: Points to the SSH config created by cloudX-proxy setup
+   - `connectTimeout`: Extended timeout (90s) for instance startup and connection establishment
+   - `serverInstallTimeout`: Additional time (120s) for VSCode server installation on first connect
+   - `showLoginTerminal`: Shows connection progress for troubleshooting
+   - `remotePlatform`: Tells VSCode that cloudx hosts are Linux systems
+
+4. **Custom SSH Config Location:**
+   If you used `--ssh-config` during setup, update the `configFile` path accordingly:
+   ```json
+   {
+       "remote.SSH.configFile": "~/.ssh/cloudx/config"
+   }
+   ```
+
+### How Connections Work
+
+Understanding the connection flow helps with troubleshooting and explains why certain timeouts are necessary:
+
+#### Step-by-Step Connection Process
+
+1. **VSCode Initiates SSH Connection**
+   - User clicks "Connect" or runs `ssh cloudx-{env}-{hostname}`
+   - SSH reads the configuration and calls cloudX-proxy as ProxyCommand
+
+2. **AWS Authentication & Instance Check**
+   - cloudX-proxy authenticates using the specified AWS profile
+   - Checks if the target EC2 instance exists and is accessible
+   - Verifies SSM agent is installed and running on the instance
+
+3. **Instance Startup (if needed)**
+   - If instance is stopped, cloudX-proxy starts it automatically
+   - Waits for instance to reach "running" state (typically 30-60 seconds)
+   - Monitors SSM connectivity until agent responds
+
+4. **SSH Key Distribution**
+   - Reads the public SSH key from the local filesystem
+   - Pushes the public key to the instance using EC2 Instance Connect
+   - Key is temporarily authorized for the current session (60 seconds)
+
+5. **SSM Tunnel Establishment**
+   - Creates a secure tunnel through AWS Systems Manager
+   - Port forwards local port to instance port 22 (SSH)
+   - Tunnel handles all network traffic encryption
+
+6. **SSH Connection Completion**
+   - SSH client connects through the established tunnel
+   - Authenticates using the private SSH key
+   - VSCode completes the remote connection setup
+
+#### Why Timeouts Are Important
+
+- **Connect Timeout (90s)**: Accounts for instance startup + tunnel establishment
+- **Server Install Timeout (120s)**: VSCode server download and installation on first connect
+- **Instance startup can take 30-90 seconds** depending on instance type and size
+- **Network conditions** may require additional time for AWS API calls
+
+#### Connection Indicators
+
+- **"Starting instance..."** - EC2 instance is being started
+- **"Waiting for SSM connectivity..."** - Instance is starting, SSM agent not ready yet  
+- **"Pushing SSH key..."** - Distributing public key via EC2 Instance Connect
+- **"Starting session..."** - Creating SSM tunnel
+- **VSCode "Installing server..."** - First-time setup of VSCode remote server
+
 ## Usage
 
 ### Command Line Options
@@ -287,7 +400,7 @@ Options:
 - `--profile` (default: vscode): AWS profile to use. The profile's IAM user should follow the format cloudX-{env}-{user}. The environment part will be used as the default environment during setup.
 - `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in the SSH config directory. This same name can be used in the connect command.
 - `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
-- `--1password` (optional): Enable 1Password SSH agent integration. Can be used as a flag or with a vault name (e.g., `--1password Private`). Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent. If a vault name is specified, that vault will be used for key storage. By default, the "Private" vault is used. Note that only the "Private" vault is enabled for SSH by default in 1Password settings.
+- `--1password` (optional): Enable 1Password SSH agent integration. Can be used as a flag or with a vault name (e.g., `--1password Private`). First searches all vaults for existing keys with name "cloudX SSH Key - {keyname}". If no existing key found, creates new keys directly in the specified (or selected) 1Password vault and configures SSH to use the 1Password SSH agent. If a vault name is specified, that vault will be used for key storage; otherwise, prompts user to select from available vaults. By default, the "Private" vault is used when no vault specified. Note that only the "Private" vault is enabled for SSH by default in 1Password settings - other vaults must be manually enabled in 1Password SSH agent settings.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
 - `--instance` (optional): EC2 instance ID to set up connection for. If provided, skips the instance ID prompt.
 - `--hostname` (optional): Hostname to use for SSH configuration. If not provided, a hostname will be generated from the instance ID in non-interactive mode or prompted for in interactive mode.
@@ -405,20 +518,36 @@ These permissions are required to bootstrap the instance, so that after creation
 
 ## Troubleshooting
 
-1. **Setup Issues**
+### Common Issues
+
+1. **Python/Installation Issues**
+   - **Error: "python not found"** - Ensure Python 3.9+ is installed and in PATH
+   - **Error: "uvx command not found"** - Install uv: `pip install uv`
+   - **Error: "Package not found"** - Try updating uv: `pip install --upgrade uv`
+   - **ImportError/ModuleNotFoundError** - Check Python version compatibility (`python --version`)
+
+2. **Setup Issues**
    - If AWS profile validation fails, ensure your user ARN matches the cloudX-{env}-{user} format
    - For 1Password integration, ensure the CLI is installed and you're signed in
    - Check that ~/.ssh/vscode directory has proper permissions (700)
    - Verify main ~/.ssh/config is writable
 
-2. **Connection Timeout**
+2. **VSCode Connection Issues**
+   - **Error: "Could not establish connection"** - Check VSCode SSH config file path in settings
+   - **Error: "Host not found"** - Run `uvx cloudx-proxy list` to verify host configuration
+   - **Timeout during connection** - Instance may be starting up (wait 2-3 minutes)
+   - **"Installing server" hangs** - Increase `serverInstallTimeout` to 180+ seconds
+   - **Connection works in terminal but not VSCode** - Verify `remote.SSH.configFile` setting
+
+3. **Connection Timeout**
    - Ensure the instance has the SSM agent installed and running
    - Check that your AWS credentials have the required permissions
    - Verify the instance ID is correct
    - Increase the VSCode SSH timeout if needed
    - Check if the instance is starting up (can take several minutes)
+   - **Region mismatch** - Ensure AWS profile region matches instance location
 
-3. **SSH Key Issues**
+4. **SSH Key Issues**
    - If using 1Password SSH agent, verify agent is running (~/.1password/agent.sock exists)
    - Check file permissions (600 for private key, 644 for public key)
    - Verify the public key is being successfully pushed to the instance
@@ -427,21 +556,59 @@ These permissions are required to bootstrap the instance, so that after creation
      * SSH agent is enabled in 1Password settings
      * Keys are added to the SSH agent in 1Password
      * The key is visible with `op item list --categories "SSH Key"`
+     * Keys follow the naming convention "cloudX SSH Key - {keyname}" for automatic discovery
      * If using a vault other than "Private", ensure that vault is enabled for SSH in 1Password settings
      * By default, only the "Private" vault is enabled for SSH in 1Password
 
-4. **AWS Configuration**
+5. **AWS CLI and Credentials Issues**
+   - **Error: "aws command not found"** - Install AWS CLI v2 (not v1)
+   - **Error: "Unable to locate credentials"** - Run `aws configure` to set up credentials
+   - **Error: "Access Denied"** - Check IAM permissions and user ARN format
+   - **Error: "Region not specified"** - Set default region in AWS profile or use `--region`
+   - **Profile not found** - Verify profile exists: `aws configure list-profiles`
+   - **Session token expired** - For SSO/temporary credentials, re-authenticate
+
+6. **AWS Configuration**
    - Confirm AWS CLI is configured with valid credentials
    - Default region is eu-west-1 if not specified in profile or command line
    - If using AWS profile organizer, ensure your environment directory exists at `~/.aws/aws-envs/<environment>/`
    - Verify the Session Manager plugin is installed correctly
    - Check that the instance has the required IAM role for SSM
 
-5. **Instance Setup Status**
+7. **Session Manager Plugin Issues**
+   - **Error: "Session Manager plugin not found"** - Install the Session Manager plugin
+   - **Error: "Invalid session"** - Check SSM agent status on instance: `sudo systemctl status amazon-ssm-agent`
+   - **Plugin installation on macOS** - May need to add plugin to PATH manually
+   - **Plugin installation on Windows** - Restart terminal after installation
+
+8. **Instance Setup Status**
    - If setup appears stuck, check /home/ec2-user/.install-running exists
    - Verify /home/ec2-user/.install-done is created upon completion
    - Check instance system logs for setup script errors
 
+### Diagnostic Commands
+
+If you're experiencing issues, run these commands to gather diagnostic information:
+
+```bash
+# Check Python and uv versions
+python --version
+uvx --version
+
+# Verify AWS CLI and credentials
+aws --version
+aws sts get-caller-identity --profile your-profile
+
+# Test Session Manager plugin
+aws ssm start-session --target i-1234567890abcdef0 --profile your-profile
+
+# List configured SSH hosts
+uvx cloudx-proxy list --detailed
+
+# Test direct connection (replace with your values)
+uvx cloudx-proxy connect i-1234567890abcdef0 22 --profile your-profile
+```
+
 ## License
 
 MIT License - see LICENSE file for details

{cloudx_proxy-0.8.2 → cloudx_proxy-0.8.3}/README.md

@@ -20,25 +20,62 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
 - SSH tunneling through AWS Systems Manager
 - Cross-platform support (Windows, macOS, Linux)
 
+## Quick Start
+
+**TL;DR for experienced users:**
+
+1. **Install Prerequisites:**
+   ```bash
+   # Install Python 3.9+, AWS CLI v2, Session Manager plugin
+   pip install uv
+   ```
+
+2. **Run Setup:**
+   ```bash
+   # Basic setup (will prompt for AWS profile, instance ID, etc.)
+   uvx cloudx-proxy setup
+   
+   # Or non-interactive with all parameters
+   uvx cloudx-proxy setup --profile myprofile --instance i-1234567890abcdef0 --hostname myserver --yes
+   ```
+
+3. **Configure VSCode:**
+   - Install "Remote - SSH" extension
+   - Add to settings.json: `"remote.SSH.configFile": "~/.ssh/vscode/config"`
+   - Set SSH timeout: `"remote.SSH.connectTimeout": 90`
+
+4. **Connect:**
+   - Open VSCode Remote Explorer → SSH Targets
+   - Connect to `cloudx-{env}-{hostname}` (e.g., `cloudx-dev-myserver`)
+
+**First connection takes 2-3 minutes (instance startup + VSCode server install). Subsequent connections are much faster (~30s).**
+
+---
+
 ## Prerequisites
 
-1. **AWS CLI v2** - Used to configure AWS profiles and credentials
+1. **Python 3.9+** - Required for cloudX-proxy and uv package manager
+   - [Python Installation Guide](https://www.python.org/downloads/)
+   - Check your version: `python --version` or `python3 --version`
+   - Supports Python 3.9, 3.10, 3.11, 3.12+
+
+2. **AWS CLI v2** - Used to configure AWS profiles and credentials
    - [Installation Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
    - Required for `aws configure` during setup
    - Handles AWS credentials and region configuration
 
-2. **AWS Session Manager Plugin** - Enables secure tunneling through AWS Systems Manager
+3. **AWS Session Manager Plugin** - Enables secure tunneling through AWS Systems Manager
    - [Installation Guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
    - Provides the secure connection channel
    - No need for public IP addresses or direct SSH access
 
-3. **OpenSSH Client** - Handles SSH key management and connections
+4. **OpenSSH Client** - Handles SSH key management and connections
    - Windows: [Microsoft's OpenSSH Installation Guide](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui)
    - macOS/Linux: Usually pre-installed
    - Manages SSH keys and configurations
    - Provides the SSH client for VSCode Remote
 
-4. **uv** - Modern Python package installer and virtual environment manager
+5. **uv** - Modern Python package installer and virtual environment manager
    ```bash
    pip install uv
    ```
@@ -49,7 +86,7 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
    
    This means you can run cloudX-proxy directly with `uvx cloudx-proxy` without manually managing virtual environments or dependencies.
 
-5. **VSCode with Remote SSH Extension** - Your development environment
+6. **VSCode with Remote SSH Extension** - Your development environment
    - Provides the integrated development environment
    - Uses the SSH configuration to connect to instances
    - Handles file synchronization and terminal sessions
@@ -212,15 +249,91 @@ This architecture means that:
 
 ### VSCode Configuration
 
-1. Install the "Remote - SSH" extension in VSCode
-2. Configure VSCode settings:
+After completing the setup, configure VSCode to use the SSH configuration created by cloudX-proxy:
+
+1. **Install VSCode Extensions:**
+   - Install the "Remote - SSH" extension from the VSCode marketplace
+   - Optionally install "Remote Explorer" for better visualization
+
+2. **Configure VSCode Settings:**
+   Add these settings to your VSCode settings.json (Command Palette → "Preferences: Open Settings (JSON)"):
    ```json
    {
        "remote.SSH.configFile": "~/.ssh/vscode/config",
-       "remote.SSH.connectTimeout": 90
+       "remote.SSH.connectTimeout": 90,
+       "remote.SSH.serverInstallTimeout": 120,
+       "remote.SSH.showLoginTerminal": true,
+       "remote.SSH.remotePlatform": {
+           "cloudx-*": "linux"
+       }
    }
    ```
-This extra long timeout is necessary to account for the time it takes to start the instance and establish the connection.
+
+3. **Configuration Explanations:**
+   - `configFile`: Points to the SSH config created by cloudX-proxy setup
+   - `connectTimeout`: Extended timeout (90s) for instance startup and connection establishment
+   - `serverInstallTimeout`: Additional time (120s) for VSCode server installation on first connect
+   - `showLoginTerminal`: Shows connection progress for troubleshooting
+   - `remotePlatform`: Tells VSCode that cloudx hosts are Linux systems
+
+4. **Custom SSH Config Location:**
+   If you used `--ssh-config` during setup, update the `configFile` path accordingly:
+   ```json
+   {
+       "remote.SSH.configFile": "~/.ssh/cloudx/config"
+   }
+   ```
+
+### How Connections Work
+
+Understanding the connection flow helps with troubleshooting and explains why certain timeouts are necessary:
+
+#### Step-by-Step Connection Process
+
+1. **VSCode Initiates SSH Connection**
+   - User clicks "Connect" or runs `ssh cloudx-{env}-{hostname}`
+   - SSH reads the configuration and calls cloudX-proxy as ProxyCommand
+
+2. **AWS Authentication & Instance Check**
+   - cloudX-proxy authenticates using the specified AWS profile
+   - Checks if the target EC2 instance exists and is accessible
+   - Verifies SSM agent is installed and running on the instance
+
+3. **Instance Startup (if needed)**
+   - If instance is stopped, cloudX-proxy starts it automatically
+   - Waits for instance to reach "running" state (typically 30-60 seconds)
+   - Monitors SSM connectivity until agent responds
+
+4. **SSH Key Distribution**
+   - Reads the public SSH key from the local filesystem
+   - Pushes the public key to the instance using EC2 Instance Connect
+   - Key is temporarily authorized for the current session (60 seconds)
+
+5. **SSM Tunnel Establishment**
+   - Creates a secure tunnel through AWS Systems Manager
+   - Port forwards local port to instance port 22 (SSH)
+   - Tunnel handles all network traffic encryption
+
+6. **SSH Connection Completion**
+   - SSH client connects through the established tunnel
+   - Authenticates using the private SSH key
+   - VSCode completes the remote connection setup
+
+#### Why Timeouts Are Important
+
+- **Connect Timeout (90s)**: Accounts for instance startup + tunnel establishment
+- **Server Install Timeout (120s)**: VSCode server download and installation on first connect
+- **Instance startup can take 30-90 seconds** depending on instance type and size
+- **Network conditions** may require additional time for AWS API calls
+
+#### Connection Indicators
+
+- **"Starting instance..."** - EC2 instance is being started
+- **"Waiting for SSM connectivity..."** - Instance is starting, SSM agent not ready yet  
+- **"Pushing SSH key..."** - Distributing public key via EC2 Instance Connect
+- **"Starting session..."** - Creating SSM tunnel
+- **VSCode "Installing server..."** - First-time setup of VSCode remote server
+
 ## Usage
 
 ### Command Line Options
@@ -234,7 +347,7 @@ Options:
 - `--profile` (default: vscode): AWS profile to use. The profile's IAM user should follow the format cloudX-{env}-{user}. The environment part will be used as the default environment during setup.
 - `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in the SSH config directory. This same name can be used in the connect command.
 - `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
-- `--1password` (optional): Enable 1Password SSH agent integration. Can be used as a flag or with a vault name (e.g., `--1password Private`). Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent. If a vault name is specified, that vault will be used for key storage. By default, the "Private" vault is used. Note that only the "Private" vault is enabled for SSH by default in 1Password settings.
+- `--1password` (optional): Enable 1Password SSH agent integration. Can be used as a flag or with a vault name (e.g., `--1password Private`). First searches all vaults for existing keys with name "cloudX SSH Key - {keyname}". If no existing key found, creates new keys directly in the specified (or selected) 1Password vault and configures SSH to use the 1Password SSH agent. If a vault name is specified, that vault will be used for key storage; otherwise, prompts user to select from available vaults. By default, the "Private" vault is used when no vault specified. Note that only the "Private" vault is enabled for SSH by default in 1Password settings - other vaults must be manually enabled in 1Password SSH agent settings.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
 - `--instance` (optional): EC2 instance ID to set up connection for. If provided, skips the instance ID prompt.
 - `--hostname` (optional): Hostname to use for SSH configuration. If not provided, a hostname will be generated from the instance ID in non-interactive mode or prompted for in interactive mode.
@@ -352,20 +465,36 @@ These permissions are required to bootstrap the instance, so that after creation
 
 ## Troubleshooting
 
-1. **Setup Issues**
+### Common Issues
+
+1. **Python/Installation Issues**
+   - **Error: "python not found"** - Ensure Python 3.9+ is installed and in PATH
+   - **Error: "uvx command not found"** - Install uv: `pip install uv`
+   - **Error: "Package not found"** - Try updating uv: `pip install --upgrade uv`
+   - **ImportError/ModuleNotFoundError** - Check Python version compatibility (`python --version`)
+
+2. **Setup Issues**
    - If AWS profile validation fails, ensure your user ARN matches the cloudX-{env}-{user} format
    - For 1Password integration, ensure the CLI is installed and you're signed in
    - Check that ~/.ssh/vscode directory has proper permissions (700)
    - Verify main ~/.ssh/config is writable
 
-2. **Connection Timeout**
+2. **VSCode Connection Issues**
+   - **Error: "Could not establish connection"** - Check VSCode SSH config file path in settings
+   - **Error: "Host not found"** - Run `uvx cloudx-proxy list` to verify host configuration
+   - **Timeout during connection** - Instance may be starting up (wait 2-3 minutes)
+   - **"Installing server" hangs** - Increase `serverInstallTimeout` to 180+ seconds
+   - **Connection works in terminal but not VSCode** - Verify `remote.SSH.configFile` setting
+
+3. **Connection Timeout**
    - Ensure the instance has the SSM agent installed and running
    - Check that your AWS credentials have the required permissions
    - Verify the instance ID is correct
    - Increase the VSCode SSH timeout if needed
    - Check if the instance is starting up (can take several minutes)
+   - **Region mismatch** - Ensure AWS profile region matches instance location
 
-3. **SSH Key Issues**
+4. **SSH Key Issues**
    - If using 1Password SSH agent, verify agent is running (~/.1password/agent.sock exists)
    - Check file permissions (600 for private key, 644 for public key)
    - Verify the public key is being successfully pushed to the instance
@@ -374,21 +503,59 @@ These permissions are required to bootstrap the instance, so that after creation
      * SSH agent is enabled in 1Password settings
      * Keys are added to the SSH agent in 1Password
      * The key is visible with `op item list --categories "SSH Key"`
+     * Keys follow the naming convention "cloudX SSH Key - {keyname}" for automatic discovery
      * If using a vault other than "Private", ensure that vault is enabled for SSH in 1Password settings
      * By default, only the "Private" vault is enabled for SSH in 1Password
 
-4. **AWS Configuration**
+5. **AWS CLI and Credentials Issues**
+   - **Error: "aws command not found"** - Install AWS CLI v2 (not v1)
+   - **Error: "Unable to locate credentials"** - Run `aws configure` to set up credentials
+   - **Error: "Access Denied"** - Check IAM permissions and user ARN format
+   - **Error: "Region not specified"** - Set default region in AWS profile or use `--region`
+   - **Profile not found** - Verify profile exists: `aws configure list-profiles`
+   - **Session token expired** - For SSO/temporary credentials, re-authenticate
+
+6. **AWS Configuration**
    - Confirm AWS CLI is configured with valid credentials
    - Default region is eu-west-1 if not specified in profile or command line
    - If using AWS profile organizer, ensure your environment directory exists at `~/.aws/aws-envs/<environment>/`
    - Verify the Session Manager plugin is installed correctly
    - Check that the instance has the required IAM role for SSM
 
-5. **Instance Setup Status**
+7. **Session Manager Plugin Issues**
+   - **Error: "Session Manager plugin not found"** - Install the Session Manager plugin
+   - **Error: "Invalid session"** - Check SSM agent status on instance: `sudo systemctl status amazon-ssm-agent`
+   - **Plugin installation on macOS** - May need to add plugin to PATH manually
+   - **Plugin installation on Windows** - Restart terminal after installation
+
+8. **Instance Setup Status**
    - If setup appears stuck, check /home/ec2-user/.install-running exists
    - Verify /home/ec2-user/.install-done is created upon completion
    - Check instance system logs for setup script errors
 
+### Diagnostic Commands
+
+If you're experiencing issues, run these commands to gather diagnostic information:
+
+```bash
+# Check Python and uv versions
+python --version
+uvx --version
+
+# Verify AWS CLI and credentials
+aws --version
+aws sts get-caller-identity --profile your-profile
+
+# Test Session Manager plugin
+aws ssm start-session --target i-1234567890abcdef0 --profile your-profile
+
+# List configured SSH hosts
+uvx cloudx-proxy list --detailed
+
+# Test direct connection (replace with your values)
+uvx cloudx-proxy connect i-1234567890abcdef0 22 --profile your-profile
+```
+
 ## License
 
 MIT License - see LICENSE file for details

{cloudx_proxy-0.8.2 → cloudx_proxy-0.8.3}/cloudx_proxy/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.8.2'
-__version_tuple__ = version_tuple = (0, 8, 2)
+__version__ = version = '0.8.3'
+__version_tuple__ = version_tuple = (0, 8, 3)
 
 __commit_id__ = commit_id = None

{cloudx_proxy-0.8.2 → cloudx_proxy-0.8.3}/cloudx_proxy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudx-proxy
-Version: 0.8.2
+Version: 0.8.3
 Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
 Author-email: easytocloud <info@easytocloud.com>
 License: MIT License
@@ -73,25 +73,62 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
 - SSH tunneling through AWS Systems Manager
 - Cross-platform support (Windows, macOS, Linux)
 
+## Quick Start
+
+**TL;DR for experienced users:**
+
+1. **Install Prerequisites:**
+   ```bash
+   # Install Python 3.9+, AWS CLI v2, Session Manager plugin
+   pip install uv
+   ```
+
+2. **Run Setup:**
+   ```bash
+   # Basic setup (will prompt for AWS profile, instance ID, etc.)
+   uvx cloudx-proxy setup
+   
+   # Or non-interactive with all parameters
+   uvx cloudx-proxy setup --profile myprofile --instance i-1234567890abcdef0 --hostname myserver --yes
+   ```
+
+3. **Configure VSCode:**
+   - Install "Remote - SSH" extension
+   - Add to settings.json: `"remote.SSH.configFile": "~/.ssh/vscode/config"`
+   - Set SSH timeout: `"remote.SSH.connectTimeout": 90`
+
+4. **Connect:**
+   - Open VSCode Remote Explorer → SSH Targets
+   - Connect to `cloudx-{env}-{hostname}` (e.g., `cloudx-dev-myserver`)
+
+**First connection takes 2-3 minutes (instance startup + VSCode server install). Subsequent connections are much faster (~30s).**
+
+---
+
 ## Prerequisites
 
-1. **AWS CLI v2** - Used to configure AWS profiles and credentials
+1. **Python 3.9+** - Required for cloudX-proxy and uv package manager
+   - [Python Installation Guide](https://www.python.org/downloads/)
+   - Check your version: `python --version` or `python3 --version`
+   - Supports Python 3.9, 3.10, 3.11, 3.12+
+
+2. **AWS CLI v2** - Used to configure AWS profiles and credentials
    - [Installation Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
    - Required for `aws configure` during setup
    - Handles AWS credentials and region configuration
 
-2. **AWS Session Manager Plugin** - Enables secure tunneling through AWS Systems Manager
+3. **AWS Session Manager Plugin** - Enables secure tunneling through AWS Systems Manager
    - [Installation Guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
    - Provides the secure connection channel
    - No need for public IP addresses or direct SSH access
 
-3. **OpenSSH Client** - Handles SSH key management and connections
+4. **OpenSSH Client** - Handles SSH key management and connections
    - Windows: [Microsoft's OpenSSH Installation Guide](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui)
    - macOS/Linux: Usually pre-installed
    - Manages SSH keys and configurations
    - Provides the SSH client for VSCode Remote
 
-4. **uv** - Modern Python package installer and virtual environment manager
+5. **uv** - Modern Python package installer and virtual environment manager
    ```bash
    pip install uv
    ```
@@ -102,7 +139,7 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
    
    This means you can run cloudX-proxy directly with `uvx cloudx-proxy` without manually managing virtual environments or dependencies.
 
-5. **VSCode with Remote SSH Extension** - Your development environment
+6. **VSCode with Remote SSH Extension** - Your development environment
    - Provides the integrated development environment
    - Uses the SSH configuration to connect to instances
    - Handles file synchronization and terminal sessions
@@ -265,15 +302,91 @@ This architecture means that:
 
 ### VSCode Configuration
 
-1. Install the "Remote - SSH" extension in VSCode
-2. Configure VSCode settings:
+After completing the setup, configure VSCode to use the SSH configuration created by cloudX-proxy:
+
+1. **Install VSCode Extensions:**
+   - Install the "Remote - SSH" extension from the VSCode marketplace
+   - Optionally install "Remote Explorer" for better visualization
+
+2. **Configure VSCode Settings:**
+   Add these settings to your VSCode settings.json (Command Palette → "Preferences: Open Settings (JSON)"):
    ```json
    {
        "remote.SSH.configFile": "~/.ssh/vscode/config",
-       "remote.SSH.connectTimeout": 90
+       "remote.SSH.connectTimeout": 90,
+       "remote.SSH.serverInstallTimeout": 120,
+       "remote.SSH.showLoginTerminal": true,
+       "remote.SSH.remotePlatform": {
+           "cloudx-*": "linux"
+       }
    }
    ```
-This extra long timeout is necessary to account for the time it takes to start the instance and establish the connection.
+
+3. **Configuration Explanations:**
+   - `configFile`: Points to the SSH config created by cloudX-proxy setup
+   - `connectTimeout`: Extended timeout (90s) for instance startup and connection establishment
+   - `serverInstallTimeout`: Additional time (120s) for VSCode server installation on first connect
+   - `showLoginTerminal`: Shows connection progress for troubleshooting
+   - `remotePlatform`: Tells VSCode that cloudx hosts are Linux systems
+
+4. **Custom SSH Config Location:**
+   If you used `--ssh-config` during setup, update the `configFile` path accordingly:
+   ```json
+   {
+       "remote.SSH.configFile": "~/.ssh/cloudx/config"
+   }
+   ```
+
+### How Connections Work
+
+Understanding the connection flow helps with troubleshooting and explains why certain timeouts are necessary:
+
+#### Step-by-Step Connection Process
+
+1. **VSCode Initiates SSH Connection**
+   - User clicks "Connect" or runs `ssh cloudx-{env}-{hostname}`
+   - SSH reads the configuration and calls cloudX-proxy as ProxyCommand
+
+2. **AWS Authentication & Instance Check**
+   - cloudX-proxy authenticates using the specified AWS profile
+   - Checks if the target EC2 instance exists and is accessible
+   - Verifies SSM agent is installed and running on the instance
+
+3. **Instance Startup (if needed)**
+   - If instance is stopped, cloudX-proxy starts it automatically
+   - Waits for instance to reach "running" state (typically 30-60 seconds)
+   - Monitors SSM connectivity until agent responds
+
+4. **SSH Key Distribution**
+   - Reads the public SSH key from the local filesystem
+   - Pushes the public key to the instance using EC2 Instance Connect
+   - Key is temporarily authorized for the current session (60 seconds)
+
+5. **SSM Tunnel Establishment**
+   - Creates a secure tunnel through AWS Systems Manager
+   - Port forwards local port to instance port 22 (SSH)
+   - Tunnel handles all network traffic encryption
+
+6. **SSH Connection Completion**
+   - SSH client connects through the established tunnel
+   - Authenticates using the private SSH key
+   - VSCode completes the remote connection setup
+
+#### Why Timeouts Are Important
+
+- **Connect Timeout (90s)**: Accounts for instance startup + tunnel establishment
+- **Server Install Timeout (120s)**: VSCode server download and installation on first connect
+- **Instance startup can take 30-90 seconds** depending on instance type and size
+- **Network conditions** may require additional time for AWS API calls
+
+#### Connection Indicators
+
+- **"Starting instance..."** - EC2 instance is being started
+- **"Waiting for SSM connectivity..."** - Instance is starting, SSM agent not ready yet  
+- **"Pushing SSH key..."** - Distributing public key via EC2 Instance Connect
+- **"Starting session..."** - Creating SSM tunnel
+- **VSCode "Installing server..."** - First-time setup of VSCode remote server
+
 ## Usage
 
 ### Command Line Options
@@ -287,7 +400,7 @@ Options:
 - `--profile` (default: vscode): AWS profile to use. The profile's IAM user should follow the format cloudX-{env}-{user}. The environment part will be used as the default environment during setup.
 - `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in the SSH config directory. This same name can be used in the connect command.
 - `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
-- `--1password` (optional): Enable 1Password SSH agent integration. Can be used as a flag or with a vault name (e.g., `--1password Private`). Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent. If a vault name is specified, that vault will be used for key storage. By default, the "Private" vault is used. Note that only the "Private" vault is enabled for SSH by default in 1Password settings.
+- `--1password` (optional): Enable 1Password SSH agent integration. Can be used as a flag or with a vault name (e.g., `--1password Private`). First searches all vaults for existing keys with name "cloudX SSH Key - {keyname}". If no existing key found, creates new keys directly in the specified (or selected) 1Password vault and configures SSH to use the 1Password SSH agent. If a vault name is specified, that vault will be used for key storage; otherwise, prompts user to select from available vaults. By default, the "Private" vault is used when no vault specified. Note that only the "Private" vault is enabled for SSH by default in 1Password settings - other vaults must be manually enabled in 1Password SSH agent settings.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
 - `--instance` (optional): EC2 instance ID to set up connection for. If provided, skips the instance ID prompt.
 - `--hostname` (optional): Hostname to use for SSH configuration. If not provided, a hostname will be generated from the instance ID in non-interactive mode or prompted for in interactive mode.
@@ -405,20 +518,36 @@ These permissions are required to bootstrap the instance, so that after creation
 
 ## Troubleshooting
 
-1. **Setup Issues**
+### Common Issues
+
+1. **Python/Installation Issues**
+   - **Error: "python not found"** - Ensure Python 3.9+ is installed and in PATH
+   - **Error: "uvx command not found"** - Install uv: `pip install uv`
+   - **Error: "Package not found"** - Try updating uv: `pip install --upgrade uv`
+   - **ImportError/ModuleNotFoundError** - Check Python version compatibility (`python --version`)
+
+2. **Setup Issues**
    - If AWS profile validation fails, ensure your user ARN matches the cloudX-{env}-{user} format
    - For 1Password integration, ensure the CLI is installed and you're signed in
    - Check that ~/.ssh/vscode directory has proper permissions (700)
    - Verify main ~/.ssh/config is writable
 
-2. **Connection Timeout**
+2. **VSCode Connection Issues**
+   - **Error: "Could not establish connection"** - Check VSCode SSH config file path in settings
+   - **Error: "Host not found"** - Run `uvx cloudx-proxy list` to verify host configuration
+   - **Timeout during connection** - Instance may be starting up (wait 2-3 minutes)
+   - **"Installing server" hangs** - Increase `serverInstallTimeout` to 180+ seconds
+   - **Connection works in terminal but not VSCode** - Verify `remote.SSH.configFile` setting
+
+3. **Connection Timeout**
    - Ensure the instance has the SSM agent installed and running
    - Check that your AWS credentials have the required permissions
    - Verify the instance ID is correct
    - Increase the VSCode SSH timeout if needed
    - Check if the instance is starting up (can take several minutes)
+   - **Region mismatch** - Ensure AWS profile region matches instance location
 
-3. **SSH Key Issues**
+4. **SSH Key Issues**
    - If using 1Password SSH agent, verify agent is running (~/.1password/agent.sock exists)
    - Check file permissions (600 for private key, 644 for public key)
    - Verify the public key is being successfully pushed to the instance
@@ -427,21 +556,59 @@ These permissions are required to bootstrap the instance, so that after creation
      * SSH agent is enabled in 1Password settings
      * Keys are added to the SSH agent in 1Password
      * The key is visible with `op item list --categories "SSH Key"`
+     * Keys follow the naming convention "cloudX SSH Key - {keyname}" for automatic discovery
      * If using a vault other than "Private", ensure that vault is enabled for SSH in 1Password settings
      * By default, only the "Private" vault is enabled for SSH in 1Password
 
-4. **AWS Configuration**
+5. **AWS CLI and Credentials Issues**
+   - **Error: "aws command not found"** - Install AWS CLI v2 (not v1)
+   - **Error: "Unable to locate credentials"** - Run `aws configure` to set up credentials
+   - **Error: "Access Denied"** - Check IAM permissions and user ARN format
+   - **Error: "Region not specified"** - Set default region in AWS profile or use `--region`
+   - **Profile not found** - Verify profile exists: `aws configure list-profiles`
+   - **Session token expired** - For SSO/temporary credentials, re-authenticate
+
+6. **AWS Configuration**
    - Confirm AWS CLI is configured with valid credentials
    - Default region is eu-west-1 if not specified in profile or command line
    - If using AWS profile organizer, ensure your environment directory exists at `~/.aws/aws-envs/<environment>/`
    - Verify the Session Manager plugin is installed correctly
    - Check that the instance has the required IAM role for SSM
 
-5. **Instance Setup Status**
+7. **Session Manager Plugin Issues**
+   - **Error: "Session Manager plugin not found"** - Install the Session Manager plugin
+   - **Error: "Invalid session"** - Check SSM agent status on instance: `sudo systemctl status amazon-ssm-agent`
+   - **Plugin installation on macOS** - May need to add plugin to PATH manually
+   - **Plugin installation on Windows** - Restart terminal after installation
+
+8. **Instance Setup Status**
    - If setup appears stuck, check /home/ec2-user/.install-running exists
    - Verify /home/ec2-user/.install-done is created upon completion
    - Check instance system logs for setup script errors
 
+### Diagnostic Commands
+
+If you're experiencing issues, run these commands to gather diagnostic information:
+
+```bash
+# Check Python and uv versions
+python --version
+uvx --version
+
+# Verify AWS CLI and credentials
+aws --version
+aws sts get-caller-identity --profile your-profile
+
+# Test Session Manager plugin
+aws ssm start-session --target i-1234567890abcdef0 --profile your-profile
+
+# List configured SSH hosts
+uvx cloudx-proxy list --detailed
+
+# Test direct connection (replace with your values)
+uvx cloudx-proxy connect i-1234567890abcdef0 22 --profile your-profile
+```
+
 ## License
 
 MIT License - see LICENSE file for details