This is the abridged developer documentation for Avocado Extra Docs # About these docs > Unofficial, source-verified documentation for the avocado CLI and Avocado OS, covering what the official docs leave out. This site documents the parts of [Avocado OS](https://docs.peridio.com/avocado-os/about) and the `avocado` CLI that the [official documentation](https://docs.peridio.com) doesn’t cover, covers only partly, or gets wrong. It grew out of building a real Jetson Orin product on Avocado and hitting the gaps one at a time. It is **not** affiliated with Peridio. Read it alongside the official docs, not instead of them. ## How the claims here were checked Everything on this site comes from reading the source of the exact versions below, or from inspecting real build output and booted devices. Where a page says “the CLI does X”, it’s describing what the code does, not what a doc or comment says it does. Those often differ, and the [errata page](reference/official-docs-errata/) lists the cases we found. | Component | Version checked | Where | | ---------------------- | ------------------------------------ | --------------------------------------------------------------------------- | | avocado-cli | `1.0.0-rc.5` (`2b46152`, 2026-09-17) | [avocado-linux/avocado-cli](https://github.com/avocado-linux/avocado-cli) | | avocadoctl (on device) | `0.12.0` (`fa81278`) | [avocado-linux/avocadoctl](https://github.com/avocado-linux/avocadoctl) | | meta-avocado | `scarthgap` branch at `16e6328` | [avocado-linux/meta-avocado](https://github.com/avocado-linux/meta-avocado) | | Distro feed | `2024/edge`, snapshot 16 | `repo.avocadolinux.org` | | systemd on the device | 258 | shipped in the 2024 rootfs | Every page repeats this in a **Verified against** note. The CLI is still at a release candidate and changes quickly, so treat anything version-sensitive as a snapshot, and re-check it against the source when you upgrade. ## Where to start * **New to Avocado internals?** Read the [mental model](start/mental-model/) first. It explains where each piece runs (your host, the SDK container, the device) and why that matters for almost every gotcha. * **Something is broken?** Go to [Symptoms and fixes](troubleshooting/). * **Writing `avocado.yaml`?** Use the [config schema reference](reference/config-schema/) and point your editor at the [JSON Schema](config/json-schema/). It catches typos that the CLI silently ignores. * **Short on time?** [Gotchas at a glance](start/gotchas/) lists every trap on one page. ## For LLMs and tools * [`llms.txt`](llms.txt), [`llms-full.txt`](llms-full.txt) and [`llms-small.txt`](llms-small.txt) contain the whole site as plain text. * [`schema/avocado.schema.json`](schema/avocado.schema.json) is a JSON Schema (draft 2020-12) for `avocado.yaml`. * Every page is a plain Markdown file under `src/content/docs/` in the repository. # Config schema > Every avocado.yaml key the CLI actually reads, with its type, default and behaviour, based on the CLI source rather than the published schema. **◆** marks a key that is **missing from the official schema**. The machine-readable version of this page is [`/schema/avocado.schema.json`](../../config/json-schema/). Keep in mind: * **Unknown keys are ignored silently at every level** ([details](../../config/format/#unknown-keys-are-silently-ignored)). * Every string can use [templates](../../config/templating/). * Mappings accept [`target-:` and `kernel-:` overrides](../../config/overrides/) where noted. ## Top level | Key | Type | Default | Description | | ---------------------------------------- | --------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cli_requirement` | string (semver range) | none | The CLI refuses to run if its version doesn’t satisfy this. Pre-release tags are stripped before comparing ([details](../../config/format/#cli_requirement)). | | `source_date_epoch` | integer | none | Fixed timestamp for reproducible images. Separately, `avocado sbom` reads the `SOURCE_DATE_EPOCH` environment variable. | | `default_target` | string | none | Target used when there’s no `--target` and no `AVOCADO_TARGET`. | | `default_target_board` | string | none | Lowest-priority source for `{{ avocado.target.board }}`. | | `supported_targets` | `'*'` or list of strings | none | Targets this project builds for. Also decides which bare target-name keys count as legacy overrides. | | `default_runtime` ◆ | string | none | Runtime used when there’s no `-r` and no `AVOCADO_RUNTIME`. It must name a defined runtime, which is checked at load time. | | `src_dir` | string | the config file’s directory | Root for every relative script, overlay and file path. It’s mounted at `/opt/src` in the SDK container. | | `distro` | [mapping](#distro) | | Feed release and channel | | `repos` ◆ | map of name → [repo](#repos) | none | Extra named package feeds. They’re only enabled when listed in `distro.feeds`. | | `sdk` | [mapping](#sdk) | | SDK container and cross-compile setup | | `kernel` | [kernel](#kernel), or map of name → kernel | none | Kernel source and command line | | `rootfs` ◆ | [image](#rootfs-and-initramfs), or map of name → image | `{ packages: { avocado-pkg-rootfs: '*' } }` | Rootfs contents and build | | `initramfs` ◆ | [image](#rootfs-and-initramfs), or map of name → image | `{ packages: { avocado-pkg-initramfs: '*' } }` | Initramfs contents and build | | `permissions` ◆ | [permissions](#permissions), or map of name → permissions | none | Users and groups, referenced from `rootfs` and `initramfs` | | `runtimes` (alias `runtime`) | map of name → [runtime](#runtimes) | | Deployable runtimes | | `extensions` | map of name → [extension](#extensions) | | Extensions. Names can contain templates. | | `provision_profiles` (alias `provision`) | map of name → [profile](#provision_profiles) | | Settings for each `avocado provision` profile | | `signing_keys` | list of single-key maps (`- name: key-id`) | none | Maps friendly key names to entries in the machine’s signing-key registry | | `connect` ◆ | [mapping](#connect) | none | Defaults for `avocado connect` commands | ## `distro` | Key | Type | Default | Description | | --------------------------- | ------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `release` (alias `version`) | string or integer | none | Feed year, `2024` or `2026`. Overridden by `AVOCADO_DISTRO_RELEASE`. | | `channel` | string | none | `next`, `edge` or `stable` ([details](../../build/releases-and-channels/)). Overridden by `AVOCADO_DISTRO_CHANNEL`. | | `repo` | name of a `repos` entry, or [inline repo](#distrorepo) | `https://repo.avocadolinux.org` | The distro feed | | `feeds` ◆ | list of `repos` names | only the distro feed | Enabled feeds, highest priority first. The distro feed comes first unless you list it explicitly. | ### `distro.repo` | Key | Type | Default | Description | | -------------- | ------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `url` | string | `https://repo.avocadolinux.org` | Base URL. Don’t include `$releasever` or `$target`: the path is added for you. Overridden by `AVOCADO_REPO_URL`. | | `releasever` | string | `/` | Explicit releasever. Overridden by `AVOCADO_RELEASEVER`. | | `ca` ◆ | string (path) | none | PEM CA certificate to trust for the feed. Overridden by `AVOCADO_REPO_CA`. | | `tls_verify` ◆ | boolean | `true` | `false` skips TLS verification (testing only). `AVOCADO_REPO_INSECURE=1` does the same. | ## `repos` Each entry needs **exactly one** of `url`, `org` or `path`. | Key | Type | Description | | ---------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | `url` | string | Remote feed. `$releasever` and `$target` are expanded by the CLI. | | `org` | string | Private feed hosted on Avocado Connect, accessed through your logged-in profile. It can’t carry its own credentials. | | `path` | string | Local directory of RPMs with `repodata/`, relative to the config file. It’s bind-mounted into the container. | | `release`, `channel`, `releasever` | string | Makes this a distro-shaped feed. A `url` feed that sets these must contain `$releasever`. | | `gpgkey` | string | GPG key for package signatures | | `gpgcheck` | boolean | Default `true` when `gpgkey` is set | | `targets` | list | Only enable this feed for these targets | | `stages` | list | Only enable it during these build stages | | `username`, `password` | string | Credentials. Supply them as `{{ env.X }}`; an unset variable becomes an empty string. | | `ca`, `tls_verify` | | As in `distro.repo` | ## `sdk` | Key | Type | Default | Description | | --------------------------------- | --------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `image` | string | none, and required | SDK container image. `sdk:2024` is a moving tag; pin one ([details](../../build/releases-and-channels/#switching-release-or-channel)). | | `packages` (alias `dependencies`) | [package map](../../config/format/#package-entries) | none | Packages installed into the SDK | | `compile` | map of name → [compile section](#sdkcompilename) | none | Cross-compile steps | | `container_args` | list of strings, or one string | none | Extra `docker run` arguments. A string is split on spaces; `\ `and quotes are respected. | | `repo_url`, `repo_release` | string | none | **Legacy.** Use `distro.repo.url` and `distro.repo.releasever`. | | `disable_weak_dependencies` | boolean | none | Don’t install packages that are only recommended | | `host_uid`, `host_gid` | integer | your UID/GID | For translating file ownership back to your host. Overridden by `AVOCADO_HOST_UID` and `AVOCADO_HOST_GID`. | ### `sdk.compile.` | Key | Type | Description | | --------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `compile` | string (script path) | Runs in the SDK with `$AVOCADO_BUILD_DIR` and `$AVOCADO_SDK_PREFIX` set, and the cross toolchain in the environment (`$CC`, `$CFLAGS`, …) | | `clean` | string (script path) | Run by `avocado ext clean` | | `packages` (alias `dependencies`) | package map | Target-side build dependencies, such as `libdrm-dev` | | `package` | mapping | Package the output as an RPM. Keys: `install` (required), `version` (required), `name`, `release`, `license`, `summary`, `description`, `vendor`, `url`, `arch`, `requires`, `files`, `split._{.{summary,description,requires,files}` | An extension uses a compile section through a package entry: `mytool: { compile: , install:}