Connect to an instance over SSH

You get a shell on your instance as root, from a terminal or from an editor such as VS Code. SSH works on any instance that has one of your keys attached. It is also how you reach an instance from a Base OS image, a public image, or a custom image launched with JupyterLab Support left unticked.

Before you begin

• An instance. You can turn on SSH while it is Running or Stopped, and you can connect while it is Running.
• A role in the project that lets you update instances.
• An SSH key pair on your computer. To make one, run this command and accept the default file name. The command saves the key pair in the .ssh folder in your home folder: a private key with no file ending, and a public key with the same name ending in .pub. The private key stays on your computer.

ssh-keygen -t ed25519

Add your public key to TIR

TIR keeps its own list of SSH keys for each user, under SSH Keys in the account menu, separate from MyAccount’s, so add a key here even if it is already in MyAccount. You can also add a key while you create an instance, with Add SSH Key, or from the instance’s SSH tab.

When you add a key, paste one OpenSSH public key, on one line. TIR takes keys of type ssh-rsa, ssh-ed25519, ssh-dss, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, and the security-key types. Give each key a label of up to 50 characters that none of your other keys uses.

A key saved by PuTTY on Windows is in PuTTY’s own format, and TIR needs it in OpenSSH format. Load the key in PuTTYgen and copy the text from the box headed Public key for pasting into OpenSSH authorized_keys file.

Each person attaches keys from their own list. A teammate who needs to log in to the same instance adds their own key to their list and attaches it. For every way to add a key, see Add an SSH key.

Turn on SSH when you create an instance

Under Network & Security on the Create Instance form, pick one or more keys in SSH Keys. An instance with SSH keys also needs a security group that opens port 22. If you leave it empty, TIR selects the project’s default security group for you. With keys selected, only groups that open port 22 can be chosen.

The default group is Default-SSH-Security-Group. Every project has one, and it allows SSH from any network and all outbound traffic. You cannot change or delete it, so to accept SSH only from one address, make a security group whose SSH inbound rule has Manual Network as its Source, with your IPv4 address; a rule takes a single address. See Open a port on an instance. Attach the group, then detach Default-SSH-Security-Group, which allows SSH from any network.

The instance gets a public IP from E2E’s pool when it has SSH keys, unless you attach a reserved IP.

Turn on SSH on an existing instance

1. Open the instance and go to Network & Security > SSH.
2. Turn the SSH switch on and pick one or more of your keys.
3. Click Update. If the instance still needs a security group with an inbound rule for TCP port 22, attach one in Enable SSH Access.
4. To confirm that you want to attach the selected keys, click Continue.

On a running instance, the keys work at once, while the instance keeps running.

Connect from a terminal

While the instance is Running, copy SSH Command from Connection Details on its Overview tab. The SSH button at the top of the instance’s page gives the same command, a version with a key file, and a few commands to try once you are connected: nvidia-smi on a GPU plan, python3 -V, and pip3 install <package-name>.

You log in as root, with your key. Password sign-in is off on every instance.

ssh root@<ip-address>

Replace <ip-address> with the address in SSH Command. It is the instance’s public IP if it has one, otherwise its first reserved IP, and otherwise its VPC IP. A VPC IP is a private address, so you connect to it from a machine in the same VPC.

If your private key is in a file other than SSH’s default, name it with -i:

ssh -i ~/.ssh/<private-key-file> root@<ip-address>

Replace <private-key-file> with the name of the private key that matches a key attached to the instance. The first time you connect to an address, SSH asks you to accept the host’s fingerprint; type yes. On a TIR pre-built image, the host key stays the same across a restart, so you accept it only once. You then get a prompt on the instance, in /root, and every command you type runs there as root.

Keep your work in /home/jovyan, the workspace. It survives restarts, stops, and starts, as do your mounted datasets and file systems, while everything else in the container returns to the image’s contents. A restart also ends your SSH session and every program you started. See Where your files live.

Connect from VS Code or another editor

An editor that works over SSH, such as VS Code with the Remote - SSH extension, uses the same user, address, and key as the terminal. Add the instance to the SSH configuration file on your computer, ~/.ssh/config:

Host tir-instance
    HostName <ip-address>
    User root
    IdentityFile ~/.ssh/<private-key-file>

Replace <ip-address> with the address in SSH Command, and <private-key-file> with your private key. In VS Code, run Remote-SSH: Connect to Host from the Command Palette and choose tir-instance. When the editor asks for a folder, open /home/jovyan, so the files you edit are in the workspace. If the instance’s address changes after a stop and start, update the address in the configuration file.

Change the keys on an instance

Add or remove keys on Network & Security > SSH while the instance is Running or Stopped. On a running instance, a key you add works at once.

An instance can have several keys. To take one off, click its remove button and confirm with Remove Access. Removing the last key turns SSH off. Turning the SSH switch off and clicking Update also turns SSH off and removes every key.

When the image offers SSH as the only way in, the SSH switch stays on and at least one key stays attached.

If the connection fails

A connection that is refused right after a start or restart usually means SSH is still starting. SSH answers only while the instance is Running, so wait until it is, then connect again.

An address that stops answering after a stop and start has usually changed. The instance gives back its public IP from E2E’s pool when it stops, and a start can bring a different one. Copy SSH Command again, or reserve the address to keep it the same; see Manage IP addresses on an instance.

Permission denied (publickey) means the key you log in with is missing from the instance, or you logged in as a user other than root. Attach the key on the SSH tab, or connect as root.

When a connection times out, the port is most likely closed. Check that the instance has a security group with an inbound rule for port 22 from your address.

For other messages, see Troubleshooting TIR Instances.

The same connection moves files to and from the instance; see Copy files to and from an instance. To reach an app you run on the instance from your browser instead, see Open a port on an instance.