sonic ssh


sonic ssh [IDENTIFER]


Ssh into a instance using identifier. identifer can be several things: instance id, ec2 tag, ECS service name, etc.

  • EC2 instance id. Example: i-067c5e3f026c1e801
  • EC2 tag value. Any tag value is search, the tag key does not matter only the tag value matters. Example: hi-web
  • ECS service. Example: my-ecs-service
  • ECS container instance id. Example: 7fbc8c75-4675-4d39-a5a4-0395ff8cd474
  • ECS task id. Example: 1ed12abd-645c-4a05-9acf-739b9d790170

When using ecs identifiers the --cluster option is required or can be set in ~/.sonic/settings.yml.


$ sonic ssh i-067c5e3f026c1e801
$ sonic ssh hi-web
$ sonic ssh --cluster my-cluster my-ecs-service
$ sonic ssh 7fbc8c75-4675-4d39-a5a4-0395ff8cd474
$ sonic ssh 1ed12abd-645c-4a05-9acf-739b9d790170

Sonic ssh builds up the ssh command and shells out to it. For example, the following commands:

sonic ssh i-027363802c6ff314f

Translates to:


You can also tack on any command to be run at the end of the command. Example:

$ sonic ssh i-027363802c6ff314f uptime
=> ssh uptime  15:57:02 up 18:21,  0 users,  load average: 0.00, 0.01, 0.00

Specifying pem keys

The recommended way to specify custom private keys is to use ssh-agent as covered here:

But you can also specify the pem key to use with the -i option. Example:

$ sonic ssh -i ~/.ssh/id_rsa-custom

Retry option

For newly launched instances, the instance’s ssh access might not be quite ready. Typically, you must press up enter repeatedly until the instance is ready. Sonic ssh has a retry option that automates this. Example:

$ sonic ssh -r i-027363802c6ff314f

Bastion Host Support

Sonic ssh also supports a bastion host.

$ sonic ssh --bastion i-027363802c6ff314f
$ sonic ssh --bastion i-027363802c6ff314f

Here’s what the output looks like:

$ sonic ssh --bastion i-0f7f833131a51ce35 uptime
=> ssh -At ec2-user@ ssh ec2-user@ uptime
 17:57:59 up 37 min,  0 users,  load average: 0.00, 0.02, 0.00
Connection to closed.

You can also set the bastion host and other options with a settings file.


-i, [--keys=KEYS]                # comma separated list of ssh private key paths
-r, [--retry], [--no-retry]      # keep retrying the server login until successful. Useful when on newly launched instances.
    [--bastion=BASTION]          # Bastion jump host to use.  Defaults to no bastion server.
    [--cluster=CLUSTER]          # ECS Cluster to use.  Default cluster is default
    [--verbose], [--no-verbose]  
    [--noop], [--no-noop]        

Edit this page

See a typo or an error? You can improve this page. This website is available on GitHub and contributions are encouraged and welcomed. We love pull requests from you!