Build fast. Ship secure. Custom, production-ready embedded Linux for the edge, from one avocado.yaml.
One CLI to build Avocado OS images, provision devices, and ship OTA updates.
Quickstart · Install · Hardware · Ecosystem · Advanced topics · Agentic development · FAQ · Documentation · Downloads
Avocado OS is an immutable embedded Linux distribution built on top of Yocto. We run the BitBake builds for your hardware ahead of time and publish the output as RPM package feeds. We prebuild:
- Kernel and kernel modules
- Board support package (BSP)
- Rootfs and initramfs packages
- Libraries and userspace packages
- SDK toolchain for cross-compilation
You select what you need in avocado.yaml. The CLI installs these prebuilt packages and assembles the kernel image, initramfs, and rootfs into an OS image. The OS is assembled at build time, not at run time.
Because everything is prebuilt, you get:
- Fast builds. You do not run BitBake or wait for multi-hour builds.
- No build server. An everyday laptop is enough to assemble a full OS image.
- Hardware portability. To move to different hardware, simply change the target in
avocado.yaml. - One-line packages. To add a package, search our feeds and add it to your
avocado.yaml. - Fast iteration. Push an updated extension to a running device on your network with
avocado deploy. - Reproducible. Versioned package feeds and
avocado.lockpin every package, so the sameavocado.yamland lockfile install the same package versions every time, and every device runs what you tested.
Your application goes in extensions, so you can update it without a rebuild of the OS or a reboot. OS updates use A/B partitions with automatic rollback. Avocado OS also supports secure boot and encrypted storage.
See About Avocado OS for more info.
The Avocado CLI is a cross-platform tool written in Rust. It orchestrates everything you need to build and ship Avocado OS, on your machine or in CI. With the CLI, you can:
- Start a project for a hardware target or from a reference project (
avocado init) - Install the SDK toolchain and packages from the Avocado package feeds (
avocado install,avocado fetch) - Build your system extensions and the runtime image (
avocado build) - Provision a bootable image for a device (
avocado provision) - Generate an SBOM in SPDX 3.0 format for the installed packages (
avocado sbom) - Ship updates through Avocado Connect (
avocado connect upload,avocado connect deploy), or push straight to a device on your network (avocado deploy)
This builds and boots Avocado OS in QEMU, so you don't need any hardware. Install the CLI first. See the host prerequisites for your platform.
# 1. Create a project for the QEMU x86-64 target
avocado init --target qemux86-64 my-qemu-project
cd my-qemu-project
# 2. Install the SDK toolchain and packages declared in avocado.yaml
avocado install
# 3. Build extensions and the runtime image
avocado build
# 4. Provision a bootable image for the `dev` runtime
avocado provision dev
# 5. Boot it with the SDK's built-in QEMU (log in as root, empty password)
avocado sdk run -iE vm devTo start from a complete, buildable example instead, run avocado init --reference qemu-quickstart or pick another project from avocado-linux/references.
The init → install → build → provision flow is the same on a board, and avocado provision --list shows the provisioning profiles for the current target. Pick a guide:
- Raspberry Pi 5 (target
raspberrypi5) - NVIDIA Jetson Orin Nano (target
jetson-orin-nano-devkit) - NXP FRDM i.MX 93 (target
imx93-frdm) - Any other supported target
brew tap avocado-linux/tap
brew install avocado-cliEvery GitHub Release attaches tarballs for these platforms:
| OS | Architecture | Target triple |
|---|---|---|
| macOS | Apple Silicon | aarch64-apple-darwin |
| macOS | Intel | x86_64-apple-darwin |
| Linux | aarch64 (static) | aarch64-unknown-linux-musl |
| Linux | x86_64 (glibc) | x86_64-unknown-linux-gnu |
| Linux | x86_64 (static) | x86_64-unknown-linux-musl |
| Windows | x86_64 | x86_64-pc-windows-msvc |
For other install options, see the installation guide.
avocado upgrade # self-update from GitHub Releases
avocado upgrade --version <version> # pin a specific versionIf you installed with Homebrew, brew upgrade avocado-cli keeps Homebrew in sync.
# zsh: add to ~/.zshrc
source <(avocado completion zsh)
# bash: add to ~/.bashrc
source <(avocado completion bash)| Vendor | Example boards | Get started |
|---|---|---|
| NVIDIA Jetson | Orin Nano Developer Kit, Orin NX, AGX Orin, AGX Thor | Jetson guide |
| NXP i.MX | i.MX 8MP EVK, i.MX 93 EVK, FRDM i.MX 93, FRDM i.MX 91 | FRDM i.MX 93 guide |
| Qualcomm | RB3 Gen 2, Thundercomm Rubik Pi 3 | Any-target guide |
| Raspberry Pi | Raspberry Pi 5, Raspberry Pi 4 Model B, Raspberry Pi Zero 2 W | Raspberry Pi guide |
| Intel | x86-64-v2, x86-64-v3 | Any-target guide |
| QEMU (no hardware) | qemux86-64 |
QEMU guide |
Boards from Advantech, CompuLab, Grinn, OnLogic, Seeed, SolidRun, STMicroelectronics, and Variscite are supported too. See the support matrix for up to date listing of every board, its target name, and which Yocto LTS feed (2024 or 2026) it's supported by.
flowchart LR
feed["Avocado package feed<br/>(prebuilt with Yocto)"] --> yaml["avocado.yaml"]
yaml --> sdk["SDK<br/>(avocado-vm or Docker)"]
sdk --> out["extensions +<br/>runtime image"]
out -- "provision / deploy" --> dev["device"]
out -- "connect upload" --> connect["Avocado Connect<br/>(OTA to fleets)"]
- Describe your target, extensions, and runtimes in
avocado.yaml, and search and specify the packages you need from the package feed (see the configuration reference). - Install: the CLI pulls the SDK and the packages you declared from the package feed.
- Build: inside the SDK, the CLI builds your extensions and assembles an immutable runtime image.
- Ship: provision the image onto a device, or upload it to Avocado Connect and deploy it to a cohort over the air.
| Repository | What it is |
|---|---|
| meta-avocado | The meta layers: the Avocado distro layer for Yocto. |
| avocado-os | The core Avocado OS distribution and its built extensions. |
| avocado-cli (this repo) | The avocado command for initializing, building, provisioning, and deploying projects. |
| references | Complete example projects you can start from with avocado init --reference. |
| avocado-mcp | MCP server that turns an AI coding assistant into an Avocado OS co-pilot. |
| avocadoctl | On-device runtime control and commands, shipped in Avocado OS images. |
| avocado-conn | Avocado Connect daemon that runs on the device, packaged as an Avocado extension. avocado connect init writes its config. |
| avocado-rat | Avocado Connect tunnel daemon that runs on the device, packaged as an Avocado extension. |
| stone | CLI for managing Avocado stones, the provisioning manifests behind avocado provision. |
| homebrew-tap | Homebrew tap for Avocado tools. |
| docs | Source for docs.peridio.com (under the peridio organization). |
Board support (bsp-*), system extensions (ext-*), and vendored Yocto layers (vendor-*) each have their own repositories in the avocado-linux organization.
Avocado Desktop is not open source. It's a free native app for macOS and Linux that bundles the CLI and toolchain. Get it from Downloads.
When you are ready to go past the Quickstart, the Developer Reference has guides for each of these topics. Except for the Yocto topics, you drive each of them with the avocado CLI and avocado.yaml:
- Build and customize: cross-compilation, custom kernel, rootfs and initramfs, device-tree overlays, and seeding the var partition
- Develop on hardware: hardware in the loop, container dev mode, and remote tunnel
- Security: boot signing, encrypted /var, and filesystem verity
- Reproducible builds: lockfiles and build stamps
- Yocto: modifying OS components and the meta-avocado layer
- AI assistants: install the Avocado OS MCP server in Claude Code, Cursor, and other MCP clients
Field Notes are dated, reproducible write-ups of real builds on real hardware. Some to start with:
- A four-model DeepStream vision pipeline on Jetson Orin Nano in about 14 minutes
- From QEMU to Raspberry Pi to Jetson with one codebase
- LUKS2, dm-verity, IMA/EVM, and TPM2-sealed keys on the i.MX 93
- Two boots to trust an update: A/B rollback and TUF
- Native ROS 2 Humble on Avocado OS
The open source Avocado OS MCP server gives your AI assistant the tools and knowledge to work with Avocado OS. It works in Claude Code, Cursor, Codex, and other MCP clients. The MCP server knows the avocado CLI, its commands, and the avocado.yaml schema. Describe what you want in plain language, and the assistant runs the CLI for you:
- Port your codebase.
/package-coveragereads your Dockerfile or SBOM, checks each dependency against the live package feed, and writes a report of what is present and what is missing. - Start a project.
/start-avocado-projectpicks a target and a matching reference project, then scaffolds a validatedavocado.yaml. - Add packages. Ask for a library, and the assistant finds it in the feed and adds it to your extension.
- Build and deploy.
/build-and-deploybuilds your project, sideloads it to a running device, and examines the result. - Debug. The assistant diagnoses failed builds and debugs a device over UART or SSH.
To get started, see installation and usage. In this Field Note, an agent turns a plain-English description into a Rust metrics exporter on a Raspberry Pi 4.
Do I need Yocto expertise? No. Avocado OS is built on top of Yocto, but the CLI installs prebuilt packages, so you never write recipes or run BitBake. See About Avocado OS.
Can I try it without hardware? Yes. The Quickstart builds and boots an image in QEMU. See the QEMU guide.
How is it licensed? The CLI is open source under the Apache License 2.0. Avocado Connect, the fleet management and OTA service, is a separate hosted service. Every organization starts on a free Developer tier (plans). You can build, provision, and avocado deploy without it.
Where do I ask questions? On Discord. Report bugs in GitHub issues.
- Ask questions on Discord. Report bugs and request features in GitHub issues.
- Read CONTRIBUTING.md and the Code of Conduct before opening a pull request.
- Report security issues privately as described in SECURITY.md.
If the Avocado CLI is useful to you, a star helps other embedded developers find it.