SSH Connection

SSH connection allows for advanced controller configuration, access to configuration files, and executing system commands. It's useful for:

• Manual editing of YAML configuration files
• Troubleshooting
• Network configuration (e.g., static IP address)
• Operating system updates

Prerequisites

• Controller's IP address (you can find it on the controller's display or in your router's admin panel)
• SSH client (built into Windows 10+, Linux, and macOS)

Connection via Ethernet

Windows

1. Press the Start button
2. Type cmd and press Enter
3. In the terminal window, type:

ssh boneio@CONTROLLER_IP_ADDRESS

You can also use Windows Terminal: https://github.com/microsoft/terminal

Linux / macOS

1. Open a terminal (e.g., GNOME Terminal, XFCE Terminal, Terminal.app)
2. Type:

ssh boneio@CONTROLLER_IP_ADDRESS

First connection

On the first connection, you'll be asked to accept the SSH key:

The authenticity of host '192.168.1.100 (192.168.1.100)' can't be established.
ED25519 key fingerprint is SHA256:...
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Type yes and press Enter.

Login credentials

• Username: boneio
• Password:
  • on a controller set up with version 1.6 or later — the password you chose for the administrator account in the first-time setup. Until the wizard is completed, SSH login with a password is not possible at all.
  • on an older controller — Black, unless you have changed it. Change it (see below): the boneio user can become root.

Changing the panel password later does not change the SSH password — see Changing password. Logging in directly as root over SSH is switched off.

After three wrong passwords the connection is closed. Your computer then has to wait five minutes before the controller lets it connect again (the same goes for any connection you close after a wrong password), and the wait grows, up to an hour, if it keeps happening. That is what makes guessing the password hopeless. A typo followed by the right password in the same connection costs nothing.

Connection via USB

If the controller doesn't have a network connection, you can connect via USB cable:

1. Connect a USB cable to the USB port of the controller and to your computer
2. Wait for the computer to recognize the network device
3. Your computer will receive an IP address from the 192.168.7.x range
4. The controller will be available at 192.168.7.2

ssh boneio@192.168.7.2

Basic commands

After logging in, you can use the following commands:

Navigate to configuration directory

cd ~/boneio

List configuration files

ls -la ~/boneio/

Edit configuration file

nano ~/boneio/config.yaml

Restart boneIO service

sudo systemctl restart boneio

Check service status

sudo systemctl status boneio

View logs

journalctl -u boneio -f

Changing password

The simplest way is the panel: Settings → Access → User accounts, the SSH login password card, Change SSH password. It asks for the current SSH password and the new one twice — see SSH login password.

Over SSH, the same thing is:

passwd

You'll be prompted to enter the current password, then type the new password twice. If the boneio login has no password at all, this is the only way — the panel has no current password to check.

Troubleshooting

Connection refused

• Check if the controller is powered on and connected to the network
• Make sure you're entering the correct IP address
• Check if the SSH service is running on the controller

Connection closed at once, after earlier wrong passwords

If the connection is closed before you are even asked for a password, and you mistyped it shortly before, the controller is making your address wait — see Login credentials. Wait five minutes and connect again.

Connection timeout

• Check if your computer and the controller are on the same network
• Check your computer's firewall settings

SSH key error

If you get an error related to SSH key change (e.g., after reinstalling the system on the controller):

ssh-keygen -R CONTROLLER_IP_ADDRESS

Then try connecting again.