Skip to main content

A utility to enable easy SSH connections to AWS EC2 instances.

Project description

SSH into your project-specific AWS EC2 instances by name, without having to remember IP addresses & private keys, or a curating a SSH config.

Turn this: ssh -i ~/.ssh/project-key.pem ubuntu@

Into this: aws-ssh compute

Getting Started


AWS-SSH requires Python 2.7 or greater on a POSIX system. You will also need to have the AWS CLI installed and configured.


Pip is the recommended method:

$ pip install aws-ssh

I recommend installing this into a virtualenv, and then symlinking the binaries to your PATH. For example:

$ mkvirtualenv -p $(which python3) aws-ssh # Python 3 recommended
$ pip install aws-ssh
# Assuming ~/bin/ is in your $PATH...
$ ln -s ~/.virtualenvs/aws-ssh/bin/{aws-ssh,awssh,ssh-ec2} ~/bin/
$ deactivate

You should now be able to use AWS-SSH outside of your virtualenv!


Once installed, you need to create a project. Projects are collections of EC2 instances that share a common set of parameters. For example, I may be working on the squanch project, with the following instances in my AWS account:

  • squanch-compute -
  • squanch-web -
  • squanch-data -

Assuming I keep my squanch-related code in ~/code/squanch, I will first need to initialize an AWS-SSH project within that directory:

$ cd ~/code/squanch
$ aws-ssh --init
Please provide the full path ot the directory containing all private keys: ~/.ssh/
Please provide a name for this project: squanch
Please provide the AWS profile to use: default
Please provide the name of the private key used for authentication (including extension): squanch.pem
Please provide the prefix for EC2 names: squanch-
Please provide the root directory for the project: ~/code/squanch

This will create an .awssshconfig file in the project root directory. You can manage it under version control to get the team on the same page :-)

Now that AWS-SSH has been configured, time to connect to an instance!

$ cd ~/code/squanch
$ aws-ssh web
# Successful SSH connection to



  • AWS-SSH attempts to guess the username for an instance by testing various usernames. Right now, the sequence of user names is fixed (and based off common AMI usernames). In a future release, this will be configurable.
  • If your access is dependent on custom routing (e.g., behind a lazy VPN), you may need to abort the connection attempt (via ^C) and manually add a route for the instance.


Contributions welcome! Be sure to use the development package, available under the dev extra.

$ git clone
$ cd aws-ssh
$ pip install -e .[dev]

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for aws-ssh, version 0.0.1
Filename, size File type Python version Upload date Hashes
Filename, size aws-ssh-0.0.1.tar.gz (10.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page