SSH - commaai/openpilot GitHub Wiki

NOTE: 🚧 openpilot 0.8.3 mandates usage of keys from a personal GitHub account and changes the SSH port from 8022 to 22.

Before You Start

  1. You need a GitHub account. Make one if you don't already have one.
  2. Enable SSH on your comma device:
    • Two: Settings -> Network -> Enable SSH
    • Three: Settings -> Network -> Advanced -> Enable SSH

Once that's done, pick an entry below to follow.

Table of Contents

Beginner

NOTE: If you're just doing this to try to install forks, tunes, or whatnot, you may be better served by Shane's Fork Installer especially as a beginner. Of course, deeper debugging and whatnot usually eventually requires SSH access setup which the fork installer won't help with.

Option 1 - Putty SSH Client

(✨ Instructions are updated for 0.8.3+)

Putty is a simple beginner friendly way to connect to a comma device via SSH.

  1. Download and install Putty.
  2. Use PuTTYgen (part of Putty) to generate a key. Save both public (for reference) and private key.
  3. Copy the contents of the textbox (probably starts with ssh-rsa, this also in your public key file) and add it to https://github.com/settings/ssh/new
  4. Get the IP address of your EON/C2 in settings under Settings > WiFi > Open WiFi Settings > More Options > Three Dots in Top Left > Advanced (Please make sure your EON and your computer connect to the same WiFi)
  5. Go to Settings [⚙️ icon] > Network > SSH Keys and press Add. Enter your GitHub username and press "⏎". You should see the SSH Keys option change to include your GitHub username with the Add button changed to Remove.
    • If a GitHub username is already there, press Remove.
    • If you change or add new SSH keys on GitHub, you should repeat this step to pull down and refresh the authorized SSH keys data on the device from GitHub.
  6. Make sure Settings [⚙️ icon] > Network > Enable SSH is enabled. It should be green.
  7. Open Putty, and enter the hostname as comma@<ip_address> where <ip_address> is your device IP and leave the port to 22 (screenshot below showing port 8022 and the root user is from an older version):

Putty Main Page

  1. Load the private key file in Connection > SSH > Auth > Private key for authentication:

Putty Private Key

  1. Finally, click Open on the bottom of the program, and if all works correctly, an SSH connection will be created. You will see a prompt with "comma@localhost:/data/openpilot$"

Option 2 - Pre-installed OpenSSH client on Windows 10 and up

(✨ Instructions are updated for 0.8.3+)

Windows 10 and up already comes with a SSH client and has everything you need to SSH into an EON/C2/C3. No additional software download or installation required.

  1. Open PowerShell. You can find PowerShell by pressing the Start Menu and typing "PowerShell".
    • You can copy and paste commands from this document by copying, and then "right-clicking" on the PowerShell window to "paste". Try copying and running this command: echo hello. The PowerShell window should print out "hello".
    • Command Prompt is not the same as PowerShell! Do not substitute Command Prompt in place of PowerShell.
  2. You'll need to have an SSH key on your PC that is added to GitHub to proceed. For instructions on how to create a key and upload it to GitHub, please follow these steps. If you have already created a key and uploaded it to GitHub, skip to the next step.
    1. Run ssh-keygen -t ed25519 -f $HOME/.ssh/id_ed25519. When there is a prompt to "Enter passphrase (empty for no passphrase):", just press Enter for no passphrase.
      • This will generate a private key and public key and store them in a ".ssh" folder in your home directory folder on your machine.
    2. Run Get-Content $HOME\.ssh\id_ed25519.pub | Set-Clipboard
      • This will copy the contents of the file id_ed25519.pub, the public key counterpart to the private key generated in the previous step, to your clipboard.
    3. Visit https://github.com/settings/ssh/new, paste the contents of your clipboard to "Key", give it a name of your choice in "Title", and press Add SSH Key.
  3. Run ssh -T [email protected] to check if GitHub is able to successfully identify you with the private key on your local system.
    • You should get "Hi <your github username here>! You've successfully authenticated, but GitHub does not provide shell access."
      • If you do not get this message, do/redo the key creation and upload instructions in the previous step.
    • If you get an "authenticity of host cannot be determined message", answer yes.
  4. Make sure your EON/C2/C3 and your computer connect to the same WiFi or network.
    • Get the IP address of your EON/C2 in settings under Settings [⚙️ icon] > Network > WiFi Settings > Three Dots in Top Right > Advanced and scroll to the bottom.
    • Get the IP address of your C3 in settings under Settings [⚙️ icon] > Network > Advanced
  6. Go to Settings [⚙️ icon] > Network [ > Advanced, if C3] > SSH Keys and press Add. Enter your GitHub username and press "⏎". You should see the SSH Keys option change to include your GitHub username with the Add button changed to Remove.
    • If a GitHub username is already there, press Remove to make Add reappear.
    • If you change or add new SSH keys on GitHub, you should repeat this step to pull down and refresh the authorized SSH keys data on the device from GitHub.
  7. Make sure Settings [⚙️ icon] > Network [ > Advanced, if C3] > Enable SSH is enabled. Newer OP has it under Settings [⚙️ icon] > Developer. It should be green.
  8. Run the command ssh [email protected] after replacing 555.555.555.555 with the IP address you discovered in the settings earlier. You should see a blue-ish prompt with "/data/openpilot" which confirms you are connected.

Option 2.Mac - Pre-installed OpenSSH client on macOS

(✨ Instructions are updated for 0.8.3+)

macOS already comes with a SSH client and has everything you need to SSH into an EON/C2/C3. No additional software download or installation required.

  1. Open Terminal. You can find Terminal by opening Spotlight in the top-right corner and typing "Terminal".
    • You can copy and paste commands from this document by copying, and then pasting with paste from the Edit menu. Try copying and running this command: echo hello. The Terminal window should print out "hello".
  2. You'll need to have an SSH key on your Mac that is added to GitHub to proceed. For instructions on how to create a key and upload it to GitHub, please follow these steps. If you have already created a key and uploaded it to GitHub, skip to the next step.
    1. Run ssh-keygen -t ed25519 -f $HOME/.ssh/id_ed25519. When there is a prompt to "Enter passphrase (empty for no passphrase):", just press Return for no passphrase.
      • This will generate a private key and public key and store them in a ".ssh" folder in your home directory folder on your machine.
    2. Run cat $HOME/.ssh/id_ed25519.pub | pbcopy
      • This will copy the contents of the file id_ed25519.pub, the public key counterpart to the private key generated in the previous step, to your clipboard.
    3. Visit https://github.com/settings/ssh/new, paste the contents of your clipboard to "Key", give it a name of your choice in "Title", and press Add SSH Key.
  3. Run ssh -T [email protected] to check if GitHub is able to successfully identify you with the private key on your local system.
    • You should get "Hi <your github username here>! You've successfully authenticated, but GitHub does not provide shell access."
      • If you do not get this message, do/redo the key creation and upload instructions in the previous step.
    • If you get an "authenticity of host cannot be determined message", answer yes.
  4. Make sure your EON/C2/C3 and your computer connect to the same WiFi or network.
    • Get the IP address of your EON/C2 in settings under Settings [⚙️ icon] > Network > WiFi Settings > Three Dots in Top Right > Advanced and scroll to the bottom.
    • Get the IP address of your C3 in settings under Settings [⚙️ icon] > Network > Advanced
  6. Go to Settings [⚙️ icon] > Network [ > Advanced, if C3] > SSH Keys and press Add. Enter your GitHub username and press "⏎". You should see the SSH Keys option change to include your GitHub username with the Add button changed to Remove.
    • If a GitHub username is already there, press Remove to make Add reappear.
    • If you change or add new SSH keys on GitHub, you should repeat this step to pull down and refresh the authorized SSH keys data on the device from GitHub.
  7. Make sure Settings [⚙️ icon] > Network [ > Advanced, if C3] > Enable SSH is enabled. Newer OP has it under Settings [⚙️ icon] > Developer. It should be green.
  8. Run the command ssh [email protected] after replacing 555.555.555.555 with the IP address you discovered in the settings earlier. You should see a blue-ish prompt with "/data/openpilot" which confirms you are connected.

Option 3 - Github's official instructions

If nothing above works, perhaps instructions based more from GitHub's official documentation may work. They certainly got paid a lot more than the person(s) writing this page.

  1. Follow the steps here: to create and test your GitHub SSH keys.
  2. Enter a GitHub username for SSH: Settings -> Network -> SSH Keys (hit Remove and then Add if needed). This enables SSH to the comma two via a private key corresponding to any public key saved in your GitHub settings.

Advanced

This section assumes that you have used SSH before. If you want to use Putty, use the instructions above.

OpenSSH or Similar Client

(⚠ Instructions are not updated for 0.8.3+)

  1. Download the private key from the openpilot repo.. Save the key file as a text file and name it something like key.pem.
  2. Open a terminal
  3. Run C$ chmod 600 key.pem` (otherwise, the system will think the text file is not safe).
  4. Get the IP address of your comma two from Settings > WiFi > Open WiFi Settings > More Options > Options (top right icon) > Advanced (please make sure your comma two and your computer connect to the same WiFi).
  5. Ping the device address from your computer to make sure it is reachable.
  6. Under a Unix/Linux, macOS terminal or Windows 10 with OpenSSH, use the command:
$ssh comma@<IP address of comma two> -p 8022 -i key.pem

Example:

$ ssh [email protected] -p 8022 -i key.pem

Connecting to ssh.comma.ai

Using OpenSSH

The instructions on ssh.comma.ai for a saved connection are slightly wrong. If you want to connect to your comma device by typing ssh comma-{dongleid} your ~/.ssh/config file should read as follows (Note the ${%h} entries in the ProxyCommand):

Host comma-*
  Port 22
  User comma
  IdentityFile ~/.ssh/my_github_key
  ProxyCommand ssh ${%h}@ssh.comma.ai -W ${%h}:%p

Host ssh.comma.ai
  Hostname ssh.comma.ai
  Port 22
  IdentityFile ~/.ssh/my_github_key

Better yet, if you just want to connect directly to your vehicle without memorizing your DongleID you can do as follows (replacing with, you know the ID. You can change the hostname to anything) then you can use ssh comma-rav4:

Host comma-rav4
  Port 22
  User comma
  IdentityFile ~/.ssh/my_github_key
  ProxyCommand ssh <DongleID>@ssh.comma.ai -W <DongleID>:%p

Host ssh.comma.ai
  Port 22
  IdentityFile ~/.ssh/my_github_key
  Hostname ssh.comma.ai

The one time connection listed on ssh.comma.ai works just fine.

Using Putty to Connect to ssh.comma.ai

Using Putty to connect to ssh.comma.ai is a bit involved. First, it assumes you have already gotten the direct SSH connection using Putty to work as described above.

  1. Start the pageant program (it is found in the same folder as Putty).
  2. Pageant will load in your taskbar . Right click the icon and select View Keys

  1. Click Add Key

image

  1. Locate and select your private key id_rsa.ppk
  2. After opening the key, you should see it in the key list

image

  1. You can click Close (pageant will keep running)
  2. Open Putty
  3. In the Host Name enter comma@<dongleid> where is your dongle id and Port 22

image

  1. Under Connection > Proxy enter the following:
  • Proxy type Local
  • Proxy hostname ssh.comma.ai
  • Port 22
  • Telnet command or local proxy command plink.exe -v %host@%proxyhost -nc %host:%port

image

  1. Go back to Session
  2. Type a name in Saved Session

image

  1. Click Save
  2. Click Open
  3. You may get a few prompts to accept the server fingerprints.

You should now be connected to your device. If you made any mistakes, you can load the saved session and fix the errors, but be sure to click Save after making any changes, or they will not be permanent.

Pageant will keep running until you log off your computer. You can also exit pageant by right-clicking the taskbar icon and selecting Exit.

Mobile SSH Clients

Troubleshoot SSH Issues

I'm hotspotting my comma two/phone. What IP do I use?

If your Android phone is connected to comma two: comma two should be 192.168.43.1

If your comma two is connected to your Android phone: comma two should be 192.168.43.2

If you're connecting your comma two to an iPhone: comma two should be 172.20.10.2

When SSH is automatically enabled/disabled

WiFi
SSH is automatically enabled with a clean comma two factory reset. It is disabled once you start installing dashcam or custom software. You then will need to enable SSH through the phone's UI settings if you want to SSH after install. SSH'ing into the phone before installing software (and typing tmux a) is helpful in understanding what is going on if you are having trouble performing your install.

LTE
You can always SSH via the LTE connection. Follow the guide here: ssh.comma.ai

Invalid Format when trying to connect

Something is wrong with your private key. Again, Putty and OpenSSH private keys are in different formats, make sure you are using the correct one.

No route to host

The IP address to your device is wrong in some way. Are both your computer and device on the same network, is the IP address typed correctly?

Permission denied (publickey,keyboard-interactive)

This is a generic authentication error and could mean many things. Did you enable SSH on the device? If you entered a GitHub Username, did you use a private key that matches one in your GitHub account? Did you correctly download and save the private key file? Does the private key have the correct permissions?

With the 0.8.3 update, the SSH requirements have changed. If you have previously SSH'd into your device, you may need to delete the old key from from the '/user/.ssh' folder. Remove the key from 'known_hosts' as well as the key file, especially if you have used workbench in the past.

port 22: Connection refused

Older devices and OSes only listened on port 8022 in the past. Use port 8022 instead.

Incoming packet was garbled on decryption

When using putty with ssh.comma.ai for the first time, plink may not properly handle accepting the host keys. To fix this, configure a SSH session to ssh.comma.ai to manually accept the host key and then the proxy session should go through properly.

Connecting VSCode to the comma three

It is possible to use VSCode Remote to remotely edit on a comma three device as the system is a glibc-based Linux system. There are some caveats though as the home directory is small. To make VSCode work, SSH in and do mkdir -p /data/vscode-server && ln -s /data/vscode-server ~/.vscode-server. After that, setup VSCode Remote to login to the comma three as the comma user and it will install its dependencies remotely.

Make driving chill. Buy a comma 3X with a car harness today!

⚠️ **GitHub.com Fallback** ⚠️