Install Drone Agent

The agent installs with a single command. The installer detects your board, installs dependencies, writes the config, registers the systemd units and starts the agent.

Mission Control’s Flash Tool shows this install command for your board. See Install paths for the recommended flow per board class.

Quick install

SSH into your companion computer and run:

curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash

The install needs root. It installs to /opt/ados/, writes config to /etc/ados/, registers the systemd units, and fetches the prebuilt Rust service binaries into /opt/ados/bin/. systemd is the supported process manager on Linux.

Setup wizard

On a fresh interactive install with none of the identity flags set, the installer opens a setup wizard in the terminal. After a welcome screen it walks seven screens. Each one shows the detected default, and Esc goes back a step:

Role: pick the node profile (drone, ground_station, workstation or compute).
Hardware: a scan of the hardware categories that matter for that profile, each marked found or not detected.
Features: a checklist of optional components, such as the World Engine extension.
Wi-Fi: join a Wi-Fi network (including a hidden one), so the wired cable can be unplugged afterwards.
Name: the node’s hostname, which is also its .local mDNS name.
Pairing: an optional Mission Control pairing code. This screen appears only for drone and ground_station.
Review: confirm the answers and install, or jump back to change one.

The wizard is skipped when a decisive flag is given, under --yes, --non-interactive, --json or --quiet, or when no terminal is attached.

What the installer does

Detect the board

Matches the board via an optional /etc/ados/board_override, the device-tree compatible string and model, then /proc/cpuinfo, falling back to generic-arm64 or generic-x86_64. There is no --board flag. See HAL and tiers.

Install system packages

Installs Python and the board-specific packages, including the RTL8812EU driver for WFB-ng unless you pass --no-rtl-driver. Uses apt on Debian and Ubuntu. On a base OS without Python 3.11 the installer downloads a self-contained CPython 3.11.

Create the runtime

Builds a Python virtual environment at /opt/ados/venv/ for the Python-backed services, and fetches the prebuilt Rust service binaries (supervisor, MAVLink router, control front, cloud relay, video, radio, logging store and the rest) into /opt/ados/bin/.

Generate device identity

Creates a 12-hex device id at /etc/ados/device-id. Pairing and mDNS use it.

Write the config

Creates /etc/ados/config.yaml with defaults for your board and records the profile and release channel in /etc/ados/profile.conf.

Install the systemd units

Installs the unit files and enables the ones your profile runs. See Systemd services.

Start the agent

Starts ados-supervisor, which brings up the units for your profile: the MAVLink proxy, the HTTP front and API, video when a camera is present, and the rest.

Install with pairing

If you have a pairing code from Mission Control, pass it during install:

curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash -s -- --pair YOUR_CODE

The node pairs to your Mission Control account during installation and appears in Mission Control as soon as it connects. See Pairing.

Upgrade an existing installation

curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash -s -- --upgrade

Or run ados update, which re-runs the installer in upgrade mode. Both keep /etc/ados/config.yaml, the device id and pairing state. See Update Drone Agent.

Installer flags

The bootstrap passes everything after bash -s -- straight to the installer. The parser rejects an unrecognised flag and aborts before touching the box, so a mistyped flag fails the install instead of being ignored.

Flag	Value	Description
`--profile`	`<<drone\|ground_station\|workstation\|compute>>`	Agent profile to install
`--name`	`<<hostname>>`	mDNS hostname to set
`--no-rtl-driver`	n/a	Skip the RTL8812EU WFB radio driver build
`--world-engine`	n/a	Install the World Engine extension (3D world model + compute offload). Default: on for workstation and compute, off for drone and ground station. An installed extension is left alone; plugin auto-update keeps it current. The last of —world-engine and —no-world-engine wins.
`--no-world-engine`	n/a	Skip the World Engine extension
`--no-reboot`	n/a	Do not perform the single automatic reboot when provisioning needs one (a camera/display overlay, an I2C dtparam). The install then reports degraded and names what is still staged.
`--pair`	`<<code>>`	Pairing code (or pass it positionally). On an already-installed box a bare code does a fast re-pair, not a reinstall.
`--upgrade`	n/a	Upgrade an existing install in place
`--force`	n/a	Clear checkpoints and reinstall
`--force-armed`	n/a	Proceed with an upgrade even when the vehicle is (or may be) armed
`--branch`	`<<name>>`	Install from a git branch (dev)
`--channel`	`<<name>>`	Release channel selector
`--version`	`<<ver>>`	Pin an explicit agent version
`--ref`	`<<commit>>`	Pin the agent package AND the prebuilt binaries to one revision, from that commit’s rev-<sha> release. Requires the edge channel.
`--artifacts`	`<<dir>>`	Install the service binaries from this directory of locally-built artifacts instead of fetching them. Each file is named for its service (ados-video) or its release asset (ados-video-aarch64) and needs its <name>.sha256 beside it; a service the directory does not carry still comes from the release. Requires the edge channel; not combinable with —ref. Linux only.
`--display`	`<<auto\|none\|id>>`	Display selection. `auto` (the ground-station default) auto-detects a panel; `none` opts out; an explicit id must be one the detected board declares.
`--camera`	`<<hint>>`	Camera hardware hint
`--wifi-ssid`	`<<ssid>>`	Join this Wi-Fi network during a headless install (so the wired cable can be unplugged)
`--wifi-pass-file`	`<<path>>`	File holding the —wifi-ssid password (omit if open; keeps it off the command line)
`--plugin-key`, `-k`	`<<path>>`	Plugin trust key (PEM) to copy into /etc/ados/plugin-keys/ on install. Repeatable.
`--uninstall`	n/a	Remove the agent
`--status`	n/a	Print install status and exit
`--plain`	n/a	Plain line output (no animation/color)
`--quiet`	n/a	Print only the final summary
`--json`	n/a	Machine output on stdout; no progress UI
`--no-color`	n/a	Disable color in the progress UI
`--ascii`	n/a	ASCII glyph fallback
`--yes`, `-y`	n/a	Accept the detected defaults; skip the interactive setup and install right away
`--non-interactive`	n/a	Never prompt; run the silent, flag-driven install (the identity flags above are the automation surface)
`--help`, `-h`	n/a	Print this help and exit

Notes on specific flags:

--channel <edge|stable>: release channel, default edge (tip of main). stable installs the signed release named by --version <X.Y.Z> and is remembered for later upgrades.
--ref <commit> requires --channel edge. With --channel stable it is refused with exit code 2 before any download, because a stable release addresses a version, not a commit.
--display <auto|none|id>: auto-detect (ground station default), opt out, or a display id the board profile declares. An undeclared id is rejected.
--wifi-pass-file <path>: file whose first line is the password for --wifi-ssid; keeps the secret off the command line. Omit it for an open network. The join never touches the interface your SSH session uses.
--profile accepts ground_station; use that spelling in scripts.

Unattended install

A fully unattended provisioning run looks like this:

curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh \
  | sudo bash -s -- \
    --non-interactive --yes \
    --profile drone --name field-01 \
    --wifi-ssid example-fleet --wifi-pass-file /root/wifi.pass \
    --plugin-key /root/example-oem-signing.pem \
    --json

Install from source

For contributors who want to change the agent code:

git clone https://github.com/altnautica/ADOSDroneAgent.git
cd ADOSDroneAgent
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ados --help

For deployment on real hardware, always use the install script instead of pip install -e. The install script catches packaging problems (missing data files, broken entry points) that editable installs hide. Editable installs are for local development only.

Install on macOS

macOS gets a rootless, per-user workstation node. Run the same bootstrap without sudo; the script refuses a root run with exit code 2. There is no prebuilt macOS installer, so the Mac path builds the installer from source (it installs the Rust toolchain first if needed) and defaults to --profile workstation.

curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | bash

The installer registers per-user LaunchAgents under $HOME/.ados, including the plugin host, which runs each extension as its own LaunchAgent in ~/Library/LaunchAgents. The World Engine extension is installed by default, as on any workstation. A macOS node has no systemd, no WFB radio and no GPIO.

Uninstall

ados uninstall

On Linux this runs the installer’s uninstall: it removes the services and binaries and keeps config and identity. Add --purge to remove config and identity as well:

ados uninstall --purge

On macOS, ados uninstall removes the LaunchAgents, and --purge also removes ~/.ados.

Directory layout after install

/opt/ados/                  # Installation root
  venv/                     # Python virtual environment
  bin/                      # Prebuilt Rust service binaries
  models/vision/            # Vision models (when vision is enabled)

/etc/ados/                  # Configuration
  config.yaml               # Main config file
  profile.conf              # Installed profile and release channel
  device-id                 # Unique device identifier
  pairing.json              # Pairing state

/var/ados/                  # Runtime data
  logd/                     # Black Box store (only when logging.store.enabled)
  recordings/               # Video recordings

/run/ados/                  # Unix domain sockets (tmpfs)
  mavlink.sock              # Binary MAVLink IPC
  state.sock                # Vehicle state IPC (length-prefixed msgpack)

/usr/local/bin/ados         # CLI

Verify the installation

# Service and setup status
ados status

# Terminal status page with the dashboard URL
ados

ados shows the dashboard URL, service state, MAVLink state, video state, network addresses and remote access state. Open the dashboard URL in a browser to finish first-run setup.

Requirements

Requirement	Minimum	Recommended
OS	Debian 11+ or Ubuntu 22.04+ (arm64, armv7l or x86_64)	Debian 12 or Ubuntu 24.04
Python	3.11 (provisioned automatically when the OS lacks it)	3.11 or 3.12
RAM	512 MB	2 GB or more
Storage	500 MB	4 GB or more
Network	Serial UART to the flight controller	Plus Wi-Fi, Ethernet or 4G

Next steps

Dashboard

Open the browser dashboard and finish first-run setup.

Pairing

Pair the node with Mission Control.

Update Drone Agent

Keep the agent current.

Get started

Set up and use

Link, video and flight systems

Reference

Diagnose

Quick install

Setup wizard

What the installer does

Install with pairing

Upgrade an existing installation

Installer flags

Unattended install

Install from source

Install on macOS

Uninstall

Directory layout after install

Verify the installation

Requirements

Next steps

Dashboard

Pairing

Update Drone Agent

​Quick install

​Setup wizard

​What the installer does

​Install with pairing

​Upgrade an existing installation

​Installer flags

​Unattended install

​Install from source

​Install on macOS

​Uninstall

​Directory layout after install

​Verify the installation

​Requirements

​Next steps

Dashboard

Pairing

Update Drone Agent

Quick install

Setup wizard

What the installer does

Install with pairing

Upgrade an existing installation

Installer flags

Unattended install

Install from source

Install on macOS

Uninstall

Directory layout after install

Verify the installation

Requirements

Next steps