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 -C ""

    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. 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. Navigate to the Embassy > SSH.

  2. Click “Add New Key”.

  3. Paste in your SSH public key (created above) and click “Submit”.

Connecting via CLI (Linux/Mac)

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

    ssh root@<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:

    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 root@embassy-xxxxxxx.local
  3. 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
  4. Reload the Tor configuration with your edits:

    systemctl reload tor
  5. 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 root@xxxxxxxxxxxxxxxxx.onion