Skip to main content
Table of contents


SSH into machines

This document explains how to SSH into machines, and what commands exist to navigate machines and applications quickly. We use a tool called GOV.UK Connect to make this easier.


If you know the class of machine you want, you can SSH straight from the command line:

$ gds govuk connect -e staging ssh cache

This will automatically SSH into a random cache machine on AWS. To see all classes, run:

$ gds govuk connect -e staging ssh *

You can also start a Rails Console on a remote server, from your local machine:

$ gds govuk connect -e staging app-console publishing-api

For a full list of commands, run gds govuk connect --help.



Sometimes you might try to ssh into a server and nothing happens. Double-check that you have added the key into the keychain like so: ssh-add -K ~/.ssh/id_rsa.

Make sure you have been granted access. For example, if you have yet to be granted access to production, your attempt to SSH into a production node will fail silently.

CLI Problems

GOV.UK Connect is a tool we use to make working with our machines quicker and easier. If it's not working, you can try manually running the commands it normally runs for you.

  • Find the class of machine you need (and which cloud it lives in).

  • Find the jumpbox for the environment you need.

  • SSH to the jumpbox.

    $ ssh -A
  • On the jumpbox, run govuk_node_list to find the machine you want.

    $ govuk_node_list -c backend
  • Still on the jumpbox, SSH to one of the machines in the list.

    $ ssh
  • Once you're on the machine you need, you can start a Rails console.

    $ govuk_app_console publishing-api

These common commands, along with govuk_node_list, live in govuk-puppet.

This page was last reviewed on 15 May 2020. It needs to be reviewed again on 15 November 2020 by the page owner #govuk-developers .
This page was set to be reviewed before 15 November 2020 by the page owner #govuk-developers. This might mean the content is out of date.