> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altnautica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the ADOS Drone Agent on your companion computer in one command.

# Installation

The agent installs with a single command. It detects your board, installs dependencies, configures systemd services, and starts everything automatically.

<Note>
  Mission Control's Flash Tool surfaces this install command automatically. See [Install paths](/getting-started/install-paths) for the recommended flow per board class.
</Note>

## Quick install

SSH into your companion computer and run:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash
```

That is it. The script handles everything from there.

<Note>
  The install script requires root access. It installs to `/opt/ados/`, creates config at `/etc/ados/`, registers systemd services, and fetches the prebuilt Rust service binaries to `/opt/ados/bin/`. systemd is the supported process manager.
</Note>

## What the install script does

<Steps>
  <Step title="Detect the board">
    Reads `/proc/device-tree/model` and matches against the 17 built-in board profiles. Sets the tier and enables the right features for your hardware.
  </Step>

  <Step title="Install system packages">
    Installs Python 3.11+, pip, virtualenv, and any board-specific packages (like the RTL8812EU DKMS driver for WFB-ng). Uses `apt` on Debian/Ubuntu systems.
  </Step>

  <Step title="Create the virtual environment">
    Sets up a Python venv at `/opt/ados/venv/` and installs the `ados-drone-agent` package from PyPI along with its dependencies (pymavlink, FastAPI, uvicorn, paho-mqtt, structlog, Rich, and more). The prebuilt Rust service binaries (supervisor, MAVLink router, control front, cloud relay, video, logging, and others) are fetched and placed in `/opt/ados/bin/`.
  </Step>

  <Step title="Generate device identity">
    Creates a unique device ID at `/etc/ados/device-id` using a chained fallback: Python uuid, OpenSSL random, or hostname-timestamp-pid. This ID is used for cloud pairing and mDNS.
  </Step>

  <Step title="Write default config">
    Creates `/etc/ados/config.yaml` with defaults tuned for your detected board. Serial port, baud rate, video resolution, and tier are all pre-filled.
  </Step>

  <Step title="Install systemd services">
    Copies service unit files to `/etc/systemd/system/` and enables them. The supervisor service starts at boot and manages all child services.
  </Step>

  <Step title="Start the agent">
    Runs `systemctl start ados-supervisor` which brings up the full service tree: MAVLink proxy, REST API, video pipeline (if a camera is detected), cloud relay, health monitor, and everything else your tier supports.
  </Step>
</Steps>

## Install with pairing

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash -s -- --pair YOUR_CODE
```

This pairs the agent to your cloud account during installation. The drone will appear in your Mission Control dashboard as soon as it connects.

## Upgrade an existing installation

To upgrade to the latest version without losing your config:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 upgrade for you:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados update
```

Both preserve `/etc/ados/config.yaml` and your pairing state. See [Updating the Agent](/drone-agent/updating) for details.

## Install from source

For contributors and developers who want to modify the agent code:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Clone the repo
git clone https://github.com/altnautica/ADOSDroneAgent.git
cd ADOSDroneAgent

# Create a virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Check the CLI surface
ados --help
```

<Warning>
  For deployment on actual hardware, always use the install script instead of `pip install -e`. The install script catches packaging bugs (missing data files, broken entry points) that editable installs skip silently. Editable installs are for local development on your laptop only.
</Warning>

## Install on macOS (for development)

You can install the package on macOS for development and packaging checks. It will not have systemd, WFB-ng, or hardware GPIO, so hardware behavior must be verified on Linux hardware.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install ados-drone-agent
```

Or with pipx for an isolated install:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pipx install ados-drone-agent
```

## Uninstall

On Linux (removes services, binary, and data, keeps config):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados uninstall
```

To remove everything including config:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados uninstall --purge
```

On macOS:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados uninstall
```

The CLI auto-detects whether you installed with pip, pipx, or uv and uses the matching uninstall command.

## Directory layout after install

```
/opt/ados/                  # Installation root
  venv/                     # Python virtual environment
  models/                   # Vision engine models (if Tier 4)

/etc/ados/                  # Configuration
  config.yaml               # Main config file
  device-id                 # Unique device identifier
  pairing.json              # Cloud pairing state
  certs/                    # TLS certificates (if enabled)

/var/ados/                  # Runtime data
  logd/                     # Black-box logging store (logs.db)
  recordings/               # Video recordings
  logs/flights/             # Flight log archive

/run/ados/                  # Unix domain sockets (tmpfs)
  mavlink.sock              # Binary MAVLink IPC
  state.sock                # JSON telemetry IPC

/usr/local/bin/ados         # CLI symlink
```

## Verifying the installation

After install, check that everything is running:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Check service and setup status
ados status

# Open the terminal status page and setup URL list
ados
```

`ados` shows the local setup webapp URL, service state, MAVLink state, video
state, network URLs, and remote access state. Open the setup URL in a browser to
finish onboarding.

## Requirements

| Requirement | Minimum                                    | Recommended               |
| ----------- | ------------------------------------------ | ------------------------- |
| OS          | Debian 11+ or Ubuntu 22.04+ (arm64/armv7l) | Debian 12 or Ubuntu 24.04 |
| Python      | 3.11                                       | 3.11 or 3.12              |
| RAM         | 512 MB (Tier 2)                            | 2 GB+ (Tier 3/4)          |
| Storage     | 500 MB                                     | 4 GB+                     |
| Network     | Serial UART to FC                          | + WiFi/Ethernet/4G        |