boneIO Documentation | Update via SSH

This guide describes manual controller update via SSH. It's useful when:

You want to install a specific software version
The web interface update doesn't work
You need more control over the update process

We highly recommend updating via the WebUI. The built-in update manager in Settings → Maintenance → Software update provides a one-click update, and lets you install an earlier version from Available Versions if something goes wrong. Use SSH updates only when the WebUI is not available or you need to install a specific version.

Requirements

SSH connection to the controller (see SSH connection guide)
Internet access on the controller

Update process

Step 1: Stop the boneIO service

sudo systemctl stop boneio

Enter the SSH password of the boneio user. On a controller set up with version 1.6 or later, this is the password you chose in the first-time setup.

Step 2: Activate the virtual environment

source ~/boneio/venv/bin/activate

Step 3: Update pip

pip3 install --upgrade pip

Step 4: Update boneIO

pip3 install --upgrade boneio

Step 5: Start the boneIO service

sudo systemctl start boneio

Simplified version

You can execute all commands in three sequences:

sudo systemctl stop boneio

source ~/boneio/venv/bin/activate && pip3 install --upgrade pip && pip3 install --upgrade boneio

sudo systemctl start boneio

Installing a specific version

To install a specific version:

pip3 install boneio==1.6.0

Replace 1.6.0 with the desired version.

Checking the version

To check the currently installed version:

pip3 show boneio | grep Version

Important changes

When introducing important changes to the application, we always inform about them in the release notes. Please read this information carefully before updating.

Troubleshooting

Error during pip installation

If you get an error related to pip, try:

python3 -m pip install --upgrade pip

Application doesn't start after update

Check the logs:

journalctl -u boneio -f

If there are configuration errors, you may need to adjust the config.yaml file for the new version. Since 1.6 a controller with a broken configuration does not keep restarting — the panel opens in recovery mode instead, where you can see the error and fix it. See Troubleshooting.

Upgrading from 1.5 over SSH

After the first start of 1.6 open the panel at https://<controller IP>:8443 — it asks you to create an administrator account (if the 1.5 panel had a password in web.auth, sign in with it instead). System migrations run by themselves on that first start. See Upgrading from 1.5 to 1.6.

Update via SSH

On this page