Overview

avocadoctl is the on-device management tool for Avocado Linux. It provides both a command-line interface and a Varlink IPC daemon for programmatic access. avocadoctl is pre-installed on all Avocado runtimes.

Capabilities

• Extension management - Merge, unmerge, enable, and disable systemd-sysext and systemd-confext based system extensions
• Runtime lifecycle - Stage, activate, inspect, and remove runtime configurations via TUF-secured repositories or local manifests
• OS bundle updates - Apply rootfs and initramfs updates using A/B partition switching with integrity verification
• Hardware-in-the-loop (HITL) testing - Mount and unmount NFS-based extensions from a remote development server
• Varlink IPC daemon - Exposes all functionality over a Unix socket for 3rd party application integration

Architecture

avocadoctl operates in a client-daemon model. The daemon listens on a Unix socket and exposes four Varlink interfaces. It is socket-activated by avocadoctl.socket, which the base OS enables by default in both the initramfs and system scopes. CLI commands connect to the daemon to execute operations. Third-party applications on the device can also connect to the same socket.

┌─────────────────┐     ┌─────────────────────────────────────┐
│  avocadoctl CLI  │────▶│  avocadoctl serve (Varlink daemon)  │
└─────────────────┘     │                                     │
┌─────────────────┐     │  org.avocado.Extensions             │
│  3rd party app   │────▶│  org.avocado.Runtimes               │
│  (C, Python, etc)│     │  org.avocado.Hitl                   │
└─────────────────┘     │  org.avocado.RootAuthority          │
                        └─────────────────────────────────────┘
                          Socket: unix:/run/avocado/avocadoctl.sock

On-Device Directory Layout

/var/lib/avocado/
├── active                          # symlink → runtimes/{active_runtime_id}
├── runtimes/
│   ├── {runtime_id}/
│   │   └── manifest.json           # runtime manifest
│   └── {runtime_id}/
│       └── manifest.json
├── images/
│   ├── {image_id}.raw              # extension images (content-addressable)
│   └── {image_id}.raw              # OS bundle images
├── os-releases/
│   └── {version_id}/
│       ├── {ext_name} → symlink    # enabled extension symlinks
│       └── {ext_name} → symlink
└── metadata/
    └── root.json                   # TUF trust anchor

Global Flags

Flag	Description
-c, --config <FILE>	Path to custom config file (default: /etc/avocado/avocadoctl.conf)
-v, --verbose	Enable verbose output
-o, --output <FORMAT>	Output format: table (default) or json
--socket <ADDRESS>	Varlink daemon socket address (overrides config)