Skip to content
Docs

Tutorials

Connect with SSH

Create a key, add it to your account and open a service's shell from your own terminal.

Updated

By the end of this walkthrough you will have a shell inside one of your running services, opened from the terminal on your own machine rather than the browser. It takes a key pair, one visit to Settings and one command copied from the console.

You need:

  • a service that is Running (the quickstart deploys one);

  • an OpenSSH client on your machine, which provides the ssh and ssh-keygen commands.

  1. Create a key pair

    Skip this step if you already have a key you want to use. Otherwise create an Ed25519 key:

    TerminalBash
    ssh-keygen -t ed25519 -C "work laptop"

    Accept the suggested file, ~/.ssh/id_ed25519, and choose a passphrase. The command writes two files: the private key, which stays on your machine, and the public key, ~/.ssh/id_ed25519.pub, which is the one Cloud needs. Print the public key:

    TerminalBash
    cat ~/.ssh/id_ed25519.pub

    It is one line starting ssh-ed25519.

  2. Add the public key to your account

    In the console, open Settings, then SSH keys, and press Add SSH key. In the Add an SSH key dialog, type a Name you will recognise, such as Work laptop, paste the whole line into Public key, and press Add key.

    The key appears in the table with its Fingerprint and "Never" under Last used. If the dialog refuses the key, its sentence says why; SSH access lists each one.

  3. Check that Cloud holds the right key

    Print the fingerprint of the file you pasted from:

    TerminalBash
    ssh-keygen -lf ~/.ssh/id_ed25519.pub

    The output contains a SHA256: string. It is the same string as the key's Fingerprint in the table.

  4. Copy the command from the Terminal page

    Open Terminal in the rail and pick your service under Service. Under Shell, keep sh, or choose bash if your image has it. The Connect with SSH line now holds the full command for that service and shell, with the gateway's address filled in. Press its copy button.

    Do not type the address yourself: the copied command is the one that matches the platform, including a port when the gateway needs one.

  5. Connect

    Paste the command into your own terminal and run it. The first time, your SSH client shows the gateway's host key fingerprint and asks whether to continue connecting. Answer yes; your client stores the key and checks it on every later connection.

    You are now in a shell inside the service's first running container. Try ls or env to see what your application sees.

  6. Leave

    Type exit or press Ctrl-D. The shell ends and ssh exits with status 0. Back in Settings, SSH keys, the key's Last used now shows today's date.

A shell left idle for thirty minutes closes with "Closed after 30 minutes idle." Anything you change inside the container is gone after the next deploy unless it is on a volume.

If the gateway refuses

What you seeWhy, and what to do
Your client says the server denied the public keyThe key is not on your account, or the id in the command is not one of your services. Copy the command again from the Terminal page. If your agent holds many keys, add -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes after ssh.
Cahaves Cloud SSH opens an interactive shell only: commands, scp and sftp are not offered.You added a command after the address, or used scp or sftp. Connect with the command as copied.
Cahaves Cloud SSH needs a terminal. Connect without -T.Your client did not ask for a terminal. Remove -T.
Nothing is running.The service has no running container. Start or deploy it, then connect again.
Too many open connections. Close one and try again.Your account already has 8 logs, terminals and SSH sessions open. Close one.

SSH access lists everything the gateway declines, and SSH refused goes deeper on each case.

Was this page helpful?