Skip to content

FAQ

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

Frequently Asked Questions

General Questions

What is cloudX-proxy?

cloudX-proxy is a tool that enables secure SSH connections from VSCode to EC2 instances using AWS Systems Manager Session Manager, without requiring direct SSH access or public IP addresses.

Do I need CloudX to use cloudX-proxy?

No! While designed for CloudX environments, cloudX-proxy works with any EC2 instance that has:

  • SSM agent installed and running
  • Proper IAM role for SSM connectivity
  • Network access for SSM communication

How is this different from regular SSH?

  • No exposed SSH ports: Uses AWS SSM tunneling instead of direct network access
  • Dynamic key management: SSH keys are injected temporarily via EC2 Instance Connect
  • AWS-native security: Access controlled through IAM permissions and policies
  • Automatic instance startup: Stopped instances are started automatically

Can I use this with existing EC2 instances?

Yes, as long as the instances have:

  • SSM agent installed (default on recent Amazon Linux, Ubuntu, Windows AMIs)
  • IAM role with SSM permissions attached
  • Network connectivity to AWS SSM service

Setup and Configuration

What AWS permissions do I need?

You need IAM permissions for:

  • ssm:StartSession and ssm:DescribeInstanceInformation
  • ec2:DescribeInstances and ec2:StartInstances
  • ec2-instance-connect:SendSSHPublicKey

See AWS Permissions for complete details.

Can I use multiple AWS profiles?

Yes! cloudX-proxy supports multiple AWS profiles. Use the --profile parameter during setup for each different environment or account.

How do I connect to instances in different regions?

Each AWS profile can have a different default region. Ensure your profile's region matches where your instances are located.

Can I use my existing SSH keys?

Yes, cloudX-proxy can use existing SSH keys. Specify the key name with --ssh-key keyname during setup.

Do I need to install cloudX-proxy?

No traditional installation needed! Use uvx cloudx-proxy to run it directly. The first run will automatically download and set up the tool.

Security Questions

Is this secure?

Yes, very secure. cloudX-proxy uses AWS Systems Manager as the primary security layer:

  • All connections encrypted through AWS APIs
  • No SSH ports exposed to the internet
  • Dynamic, temporary SSH key authorization
  • Complete audit trail through CloudTrail

See Security Model for detailed analysis.

What if my SSH key is compromised?

SSH key compromise is less concerning with cloudX-proxy because:

  • Keys don't provide direct network access to instances
  • Access still requires valid AWS credentials and IAM permissions
  • Keys are only temporarily authorized per session
  • You can easily rotate keys without instance reconfiguration

Can I use this in production?

Yes, cloudX-proxy is designed for production use with:

  • Enterprise-grade security through AWS SSM
  • Complete audit logging via CloudTrail
  • Integration with corporate identity providers through AWS SSO
  • Support for compliance requirements (SOC 2, HIPAA, FedRAMP)

How does 1Password integration work?

1Password integration provides:

  • Secure storage of SSH private keys in encrypted vaults
  • SSH agent integration for seamless authentication
  • No private keys stored on local filesystem
  • Centralized key management across devices

Connection Issues

Why is my first connection so slow?

First connections take 2-3 minutes due to:

  • Instance startup time (if stopped): 30-90 seconds
  • VSCode server download and installation: 1-2 minutes
  • Subsequent connections are much faster (~30 seconds)

My connection times out, what should I do?

Increase timeouts in VSCode settings:

{
    "remote.SSH.connectTimeout": 90,
    "remote.SSH.serverInstallTimeout": 180
}

Common causes:

  • Instance taking longer to start than expected
  • Slow internet connection affecting downloads
  • First-time VSCode server installation

Can I connect to multiple instances simultaneously?

Yes! Each instance gets its own SSH configuration entry. You can have multiple VSCode windows connected to different instances.

Why can't VSCode find my hosts?

Check that:

  • VSCode remote.SSH.configFile setting points to the correct config file
  • SSH configuration was created successfully (uvx cloudx-proxy list)
  • File permissions are correct (600 for config file)

Instance is stuck "starting up"

This can happen if:

  • Instance has startup issues (check AWS console)
  • SSM agent isn't starting properly (instance may need reboot)
  • Network connectivity issues preventing SSM communication

Advanced Usage

Can I use custom SSH configurations?

Yes! cloudX-proxy creates a three-tier SSH configuration that you can customize:

  • Generic settings for all cloudx hosts
  • Environment-specific settings
  • Host-specific overrides

How do I use different AWS environments?

Use the --aws-env parameter to organize AWS credentials:

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

Can I automate the setup process?

Yes, use non-interactive mode:

uvx cloudx-proxy setup \
    --profile myprofile \
    --instance i-1234567890abcdef0 \
    --hostname myserver \
    --yes

How do I connect from command line (not VSCode)?

After setup, use regular SSH:

ssh cloudx-{env}-{hostname}
scp file.txt cloudx-{env}-{hostname}:~/

Can I use port forwarding?

Yes! SSH port forwarding works normally:

ssh -L 8080:localhost:8080 cloudx-dev-webserver

How do I add a new instance to existing environment?

Run setup again with the new instance:

uvx cloudx-proxy setup --profile existing-profile --instance i-new-instance --hostname new-server

This reuses the existing environment configuration.

Troubleshooting

My AWS credentials aren't working

Check:

aws sts get-caller-identity --profile your-profile
aws configure list --profile your-profile

Common issues:

  • Credentials expired (especially for temporary/SSO credentials)
  • Profile name mismatch
  • Region not configured
  • Missing IAM permissions

SSH authentication fails

Check:

  • SSH key file permissions (600 for private, 644 for public)
  • SSH key format is valid (ssh-keygen -l -f keyfile.pub)
  • For 1Password: SSH agent is running and key is visible

VSCode shows "Host not found"

Run diagnostic commands:

uvx cloudx-proxy list --detailed
ssh -F ~/.ssh/vscode/config -T cloudx-your-hostname

Session Manager plugin issues

Test plugin installation:

session-manager-plugin
aws ssm start-session --target i-1234567890abcdef0 --profile your-profile

Performance Questions

How can I make connections faster?

  • Keep instances running (startup time is the biggest factor)
  • Use SSH connection multiplexing (enabled by default)
  • Choose instances in same region as your AWS profile
  • Use faster instance types for quicker startup

Does this use more bandwidth than regular SSH?

No, once connected the bandwidth usage is identical to regular SSH. The AWS SSM tunnel adds minimal overhead.

Can I use this over slow connections?

Yes, cloudX-proxy works over slow connections. You may need to:

  • Increase connection timeouts
  • Use compression (ssh -C)
  • Consider using instance types with better network performance

Integration Questions

Can I use this with other IDEs?

Yes! Any editor that supports SSH connections can use the SSH configuration created by cloudX-proxy:

  • JetBrains IDEs (IntelliJ, PyCharm, etc.)
  • Sublime Text with SFTP package
  • Vim/Emacs with tramp mode
  • Command-line tools (rsync, scp, etc.)

Does this work with Docker containers on instances?

Yes, once connected via SSH, you can use Docker normally:

ssh cloudx-dev-server
docker ps
docker exec -it container bash

Can I integrate this with CI/CD pipelines?

Yes, use non-interactive mode in scripts:

uvx cloudx-proxy setup --profile ci-profile --instance $INSTANCE_ID --hostname ci-server --yes
ssh cloudx-ci-server "deploy-script.sh"

For more detailed troubleshooting, see the Troubleshooting Guide.

Clone this wiki locally