View on GitHub


Secure AWS Shell

Download this project as a .zip file Download this project as a tar.gz file

Sash is a Secure Shell wrapper which uses aws-cli to find an instance's IP and PEM file by its name



  1. Install AWS Unified CLI
  2. Make sure you have AWS_ACCESS_KEY, AWS_SECRET_KEY and AWS_DEFAULT_REGION set in your environment
  3. Put all your PEM files under ~/.aws



git clone
cd sash
make install
echo "source ~/.local/bin/" >> ~/.bashrc
source ~/.bashrc


git clone
cd sash
make install
echo "source ~/.local/bin/" >> ~/.bash_profile
echo "export LC_ALL=en_US.UTF-8" >> ~/.bash_profile
echo "export LANG=en_US.UTF-8" >> ~/.bash_profile
source ~/.bash_profile


SSH Connect

sash my-machine-name

Also supports auto-complete (press TAB to get available machine names)

Any extra parameters will be passed to the ssh command:

> sash my-machine-name -A
+ ssh -i ~/.aws/my.pem ubuntu@ -A

To refresh the machine name cache for the autocomplete run


Using VPN

If you use VPN to connect to your instances, which means you connect via the machines private IP, you should set the environment variable SASH_USE_VPN to true - add the following line to ~/.profile:

export SASH_USE_VPN=true

This will configure the API to connect via private IPs instead of public IPs.

Multiple instances with the same name

If there are multiple instances with the same name, the first instance returned will be selected. If you want to select another, you can do it by indicating the instance's appearance index (starting from one) as a second parameter.

For example:

sash my-machine-name 3

will connect to the third instance listed with the name my-machine-name.

To see which instances are listed, and in what order, add list as the second parameter:

> sash my-machine-name list
1) my-machine-name (
2) my-machine-name (
3) my-machine-name (

Using wildcards

You can call sash with wildcards (*). This will select all instances matching the pattern, and connect to the one in the index indicated (or the first by default).

> sash my-*-name list
1) my-new-machine-name (
2) my-old-machine-name (
3) my-machine-name (

> sash my-*-name 2
Connecting to my-old-machine-name (

Connect to multiple machines at once

If you have CSSH (or tmux-cssh for OSX) installed, calling sash with all flag will connect to all machines at once:

> sash my-machine-name all
Connecting to 3 machines (

Any extra parameters will be passed to the cssh command. To pass arguments to the underlying ssh - pass it under --ssh_args as a first argument:

> sash my-machine-name --ssh_args -A -p 44
+ cssh -o '-i ~/.aws/my.pem -A' -p 44 ubuntu@ ubuntu@...

Note: All machines are expected to have the same PEM file to connect correctly

Upload/download files

Add the keyword upload to upload files to the remote machine. The next parameter should be the file to upload, and the one after that the target directory (if not declared - defaults to ~):

> sash my-machine-name upload my_file.json
+ scp -i ~/.aws/my.pem my_file.json ubuntu@

> sash my-machine-name upload my_file.json /tmp/my_directory
+ scp -i ~/.aws/my.pem my_file.json ubuntu@

Use the keyword download to download files from the remote machine (target defaults to .):

> sash my-machine-name download my_file.json
+ scp -i ~/.aws/my.pem ubuntu@ .

Optional parameters of machine index or all are supported for patterns matching more than one machine:

> sash my-machine-name upload all my_file.json
+ scp -i ~/.aws/my.pem my_file.json ubuntu@
+ scp -i ~/.aws/my.pem my_file.json ubuntu@
+ scp -i ~/.aws/my.pem my_file.json ubuntu@

Machine usernames

Sash assumes the username on your machines is ubuntu. To change that globally, set the SASH_DEFAULT_USER environment variable.

If you have a machine whose username is not the default username, you can change it by using the set_user command:

sash my-machine-name set_user ec2_user

This command uses EC2 Tags to set a Tag to that machine (named SashUserName) whose value will be used for that specific machine. To unset it, use unset_user command:

sash my-machine-name unset_user

Find machine name from private IP

Newrelic's server monitoring names the instances it monitors by their private IPs by default (ip-10-0-0-12), which is practically useless. This API finds the instance which has this private IP, and returns the instance's name tag:

private_dns_to_name ip-10-XXX-XXX-XXX