Skip to content

Installation Guide

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

Installation Guide

Complete step-by-step installation guide for cloudX-proxy.

Prerequisites

Before installing cloudX-proxy, ensure you have all required components:

1. Python 3.9+

cloudX-proxy requires Python 3.9 or later.

Check your Python version:

python --version
# or
python3 --version

Install Python if needed:

  • Windows/macOS: Download from python.org
  • Linux: Use your package manager (apt install python3, yum install python3, etc.)

2. AWS CLI v2

Used for configuring AWS profiles and credentials.

Installation:

Verify installation:

aws --version
# Should show: aws-cli/2.x.x...

3. AWS Session Manager Plugin

Enables secure tunneling through AWS Systems Manager.

Installation:

Verify installation:

session-manager-plugin
# Should show version information

4. OpenSSH Client

Handles SSH connections and key management.

Installation:

Verify installation:

ssh -V
# Should show OpenSSH version

5. uv Package Manager

Modern Python package installer and virtual environment manager.

pip install uv

Verify installation:

uvx --version
# Should show uv version

6. VSCode with Remote SSH Extension

Your development environment.

Installation:

  1. Install Visual Studio Code
  2. Install the "Remote - SSH" extension from the marketplace
  3. Optionally install "Remote Explorer" for better visualization

Installing cloudX-proxy

cloudX-proxy is available on PyPI and runs using uvx without explicit installation:

# Test installation by running setup
uvx cloudx-proxy setup --help

The first time you run this command, uvx will:

  • Create an isolated virtual environment
  • Download and install cloudx-proxy and its dependencies
  • Run the command

AWS Account Setup

Before using cloudX-proxy, you need:

1. AWS Account

  • An active AWS account with appropriate permissions
  • IAM user credentials (not root account)

2. AWS Profile Configuration

Configure your AWS credentials:

aws configure --profile myprofile

Provide:

  • Access Key ID: Your IAM user access key
  • Secret Access Key: Your IAM user secret key
  • Default region: Your preferred AWS region (e.g., us-east-1)
  • Output format: json (recommended)

3. EC2 Instances

You'll need EC2 instances to connect to. These can be:

  • CloudX instances (if you're using the CloudX environment)
  • Regular EC2 instances with SSM agent installed

Instance Requirements:

  • SSM agent installed and running
  • Proper IAM role attached for SSM connectivity
  • Instance must be in a subnet with internet access (for SSM communication)

Verification

Verify your complete setup:

# Check Python
python --version

# Check AWS CLI
aws --version
aws sts get-caller-identity --profile myprofile

# Check Session Manager plugin
aws ssm start-session --target i-1234567890abcdef0 --profile myprofile

# Check cloudX-proxy
uvx cloudx-proxy --help

Next Steps

Once installation is complete:

  1. Run Setup: Follow the Setup Command guide
  2. Configure VSCode: See VSCode Configuration
  3. Connect: Start using your EC2 instances!

Troubleshooting Installation

Python Issues

  • "python not found": Ensure Python is in your PATH
  • Version too old: Update to Python 3.9+
  • Permission denied: Use python -m pip instead of pip

AWS CLI Issues

  • "aws command not found": Check PATH, restart terminal
  • Credential errors: Run aws configure again
  • Version 1 installed: Uninstall v1, install v2

Session Manager Plugin Issues

  • "plugin not found": Check installation, restart terminal
  • macOS permission issues: Allow in System Preferences → Security
  • Windows PATH issues: Restart terminal after installation

uv/uvx Issues

  • "uvx command not found": Reinstall uv: pip install --upgrade uv
  • Package errors: Clear cache: uv cache clean
  • Permission issues: Check Python installation permissions

For more installation troubleshooting, see the Troubleshooting Guide.

Clone this wiki locally