Getting Started

Network Configuration

Your topside computer’s network configuration should be the same as for the previous Companion software. To configure it, you can follow our network setup instructions.

Web Interface

BlueOS is designed as a modular collection of services, which are accessed and configured via a combined web interface.

The web interface monitors the autopilot and other main software components. It also listens for and displays connections from other HTTP servers (on TCP ports), which allows extensions and custom integrations to provide an interface through BlueOS while remaining independent from the main BlueOS release/update cycle.

Interface Access

  • By default you can access BlueOS via blueos.local
    • This applies if the BlueOS device is connected to via a direct ethernet connection, or USB-OTG
    • On an ethernet connection you can also access BlueOS via its static IP address (
  • When BlueOS is connected to the same wifi network as your device you can also connect with it using blueos-wifi.local
  • By default if BlueOS does not have a wifi connection configured within 5 minutes of booting, it will start its own wifi hotspot which, when connected to, allows accessing the BlueOS interface via blueos-hotspot.local
    • The hotspot SSID is BlueOS (******), with password blueosap


When BlueOS is newly installed the interface provides a configuration wizard to help get things set up.

The Welcome section allows skipping the wizard if BlueOS and your vehicle have already been configured as desired:

Wizard Welcome

To support BlueOS and autopilot firmware updates, it is recommended for BlueOS to be connected to the internet:

Wizard Wifi

BlueOS supports multiple vehicle types, and allows selecting a quick-setup option for the most common ones:

Wizard Vehicle

Vehicle quick-setup involves setting appropriate parameters for the selected vehicle type and frame, as well as choosing a name for your vehicle, and changing the mDNS hostname if you would prefer to connect with something other than http://blueos.local:

Wizard Parameters

Progress is displayed for any selected configuration changes, and an up to date autopilot firmware is downloaded and installed (if using a standard vehicle type):

Wizard Progress

A completion window is shown once all configuration is done:

Wizard Complete

Interface Features

When you first open the web interface, you'll see a page that looks like this:

../Advanced Usage/Interface Overview

As a brief overview,

  • the header contains system health indicators and notifications, and some network and display configuration options
  • the sidebar allows navigating between pages, and allows restarting, freeing up space, and reporting issues
  • most pages show their content within the BlueOS interface sections, but some extensions open as full pages in a separate tab

For more details see the Advanced Usage Interface Overview section.

Updating / Releases

BlueOS supports multiple release types - we recommend the latest stable version for most people. Releases and change-logs are available on the GitHub releases page.

Connect Internet

When starting out, it's important to connect your vehicle to the internet so you can update to the latest suitable release. Internet connectivity is possible via either wifi or passed through a tether.

Connect Wifi

  1. First, click the wifi indicator to scan for available wifi networks

    Wifi Scan

  2. Select the desired network, type in the password, and click connect

    Wifi Login

  3. Once connected, the wifi icon will change to show the signal strength, and the connected wifi network will be selected on the menu

    Wifi Confirm

Tether Passthrough

Once the internet passthrough has been configured, the BlueOS header should show that it has internet connectivity.

Select Version

Now that your BlueOS has an internet connection, you can perform the update to the latest available version.

  1. Click on the hamburger menu (if the sidebar is not already open)

    Version Menu

  2. Under Settings, select BlueOS Version

    Version Chooser

  3. If you're already on the latest version, the right side of your Local Version will be blank. If not, you should see a blue Update button.

  4. Once the update button is clicked the update process will run. Please wait until it finishes - it will automatically reload the webpage for you.

Camera Streams

BlueOS is capable of configuring and streaming multiple cameras simultaneously. The first time it boots, it will automatically detect any connected H264-capable cameras and start streaming them. If not, make sure your camera is properly connected, and that BlueOS is on the latest available version. Reset settings and restart BlueOS if necessary.

Additional information is available in the Advanced Usage Video Streams section.


It is possible to connect with a Raspberry Pi 4 through its USB-C port1. Once it's connected, the interface should be available though blueos.local2.


A Raspberry Pi draws more power than many computer USB ports can provide, so a USB-C connection should generally only be used for data transfer, with a separate power supply (or through a powered USB hub).


The usb0 network interface is configured to use a DHCP server at by default, which does not provide access via the static IP address.

Mac configuration

If you are using MacOS, make sure to allow the RNDIS/ethernet gadget:

Allow Rndis

MacOS will consider a USB-OTG connection as a valid source of internet, which can be avoided by reordering your network interfaces, making sure that wifi and your actual wired internet connection interface are used with higher priority.

Network Settings
Network Service Order

Edit this page on GitHub