You are not reading the latest stable version of this documentation. If you want up-to-date information, please have a look at master.

Using SSH

Creating an SSH Key (Linux/Mac)

  1. Open a terminal and enter the following command, replacing the example email address with your own (or, alternatively, a comment):

    ssh-keygen -t ed25519

    You will be asked to Enter a file in which to save the key - we recommend you press Enter to use the default location

  2. Create a strong passphrase and save it somewhere safe, or press Enter for no passphrase

  3. It will inform you that your public key has been saved. Take note of this path:

    Your public key has been saved in /home/user/.ssh/
  4. Next, start your system’s ssh-agent and add your key to it:

    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_ed25519

    Note that if you changed the file name/location in step 1, you will need to use that file/path in this step

Registering an SSH Key

  1. In your Embassy’s web interface, navigate to Embassy > SSH.

  2. Click “Add New Key”.

  3. Back in the terminal of your workstation, display and copy your SSH public key (created above):

    cat ~/.ssh/
  4. Copy the whole resulting line that looks similar to:

    ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINH3tqX71XsPlzYhhoo9CqAP2Yx7gsGTh43bQXr1zqoq
  5. Paste that line into the Add New Key text field of your Embassy

  6. Click Submit

You are now ready to SSH into your Embassy!

Connecting via CLI (Linux/Mac)

  1. You can now access your Embassy from the command line (Linux and Mac) using:

    ssh start9@<LAN URL>

Replacing <LAN URL> with your Embassy’s LAN (embassy-xxxxxxx.local) address

Connecting via PuTTY on Windows

Community member BrewsBitcoin has created a guide for connecting via SSH using PuTTY on Windows.

Using SSH Over Tor


The following guide requires that you have already added an SSH key to your Embassy.


SSH over Tor is only supported on Linux, though it may also work on Windows with Torifier.


  1. First, you’ll need one dependency, torsocks, which will allow you to use SSH over Tor on the machine that you want access with. Select your Linux flavor to install:

    sudo apt install torsocks
  2. SSH in:


    The changes you make here are on the overlay and won’t persist after a restart of your Embassy.

    ssh start9@embassy-xxxxxxx.local
  3. Elevate yourself to root for the rest of the ssh session:

    sudo -i
  4. Using Vim or Nano, add the following 2 lines to /etc/tor/torrc

    HiddenServiceDir /var/lib/tor/ssh
    HiddenServicePort 22


    You can also add these lines by running the following command:

    echo "HiddenServiceDir /var/lib/tor/ssh" >> /etc/tor/torrc && echo "HiddenServicePort 22" >> /etc/tor/torrc
  5. Reload the Tor configuration with your edits:

    systemctl reload tor
  6. Gather the “.onion” address you just created:

    cat /var/lib/tor/ssh/hostname


To log in, simply use the following command, using the “.onion” hostname you printed above:

torsocks ssh start9@xxxxxxxxxxxxxxxxx.onion