Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
2a8f808
extensions/container-agent-dev: Add device-side control agent
jetm Jul 22, 2026
3e8d505
container-agent-dev: Add loopback registry proxy for device image pulls
jetm Jul 22, 2026
9820ce7
container-agent-dev: Implement sync handler with ordered pull/restart
jetm Jul 22, 2026
71e6a53
extensions/container-agent-dev: Add container dev mode agent extension
jetm Jul 23, 2026
c01b518
container-agent-dev: Add ring-only provider guard script
jetm Jul 23, 2026
2b63520
container-agent-dev: Enforce the provider guard in the build hook
jetm Jul 23, 2026
8d3c184
container-agent-dev: write the active-image pointer after the restart
jetm Jul 27, 2026
019648d
container-agent-dev: keep serving loopback after an accept error
jetm Jul 27, 2026
0262c7c
container-agent-dev: bound the proxy's accept retries
jetm Jul 28, 2026
5f76c51
container-agent-dev: report the running digest from the restart, not …
jetm Jul 28, 2026
1a829c4
container-agent-dev: confine the agent, dropping podman support
jetm Jul 28, 2026
42050c6
container-agent-dev: test the proxy's accept-error retry policy
jetm Jul 28, 2026
03269c3
container-agent-dev: make losing the proxy end the process
jetm Jul 29, 2026
1485c8e
container-agent-dev: stop claiming a pointer write that failed
jetm Jul 29, 2026
8430394
container-agent-dev: restart the owning unit so a pulled image actual…
jetm Jul 31, 2026
88b4b0b
container-agent-dev: point the service's image ref at what was pulled
jetm Jul 31, 2026
05118c1
container-agent-dev: make the agent's happy path actually work
jetm Aug 4, 2026
3ea1443
container-agent-dev: carry the owning unit on the wire and bound the …
jetm Aug 4, 2026
a93b392
container-agent-dev: make the two timeout tests fail rather than hang
jetm Aug 4, 2026
4c8f385
agent: import the container dev agent crate with its history
jetm Sep 9, 2026
3f5a45a
Add the packaging for avocado-ext-container-agent-dev
jetm Sep 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,11 @@ name: Release
# Package + publish on a version tag. The matrix lives here (the caller owns it);
# each leg calls the single-combo reusable helper. The publish feed is derived from
# distro-release/distro-channel. The tag must equal the avocado.yaml version.
#
# One row per target in avocado.yaml `supported_targets`. Keep the two lists in
# step: a target published here but not declared there ships something the
# extension does not claim to support, and the reverse claims support for
# something never built.
on:
push:
tags:
Expand All @@ -13,11 +18,16 @@ on:
jobs:
publish:
strategy:
# Each target reports its own outcome. Without this one target's failure
# cancels the rest, and a partial publish looks like a total one.
fail-fast: false
matrix:
include:
- { target: qemux86-64, distro-release: "2024", distro-channel: next }
# Add once your target is published in the 2026 feed:
- { target: imx93-frdm, distro-release: "2024", distro-channel: next }
# Add once these targets are published in the 2026 feed. As of
# 2026-09-09 the 2026 feed carries jetson-agx-thor, qemuarm64 and
# qemux86-64 only, so an imx93-frdm row there would fail.
# - { target: qemux86-64, distro-release: "2026", distro-channel: next }
uses: avocado-linux/actions/.github/workflows/extension-release.yml@v1
with:
Expand Down
11 changes: 11 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Cargo build output for the staged crate.
/agent/target/

# Cross-compilation config written by cad-compile.sh at build time. It pins one
# machine's SDK sysroot path, so a committed copy is wrong for everyone else.
/agent/.cargo/

# avocado-cli build state. .avocado-state is a JSON file, not a directory, so it
# needs a slash-free pattern - a trailing slash silently fails to match it.
/.avocado-state
/avocado.lock
124 changes: 64 additions & 60 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,64 +1,68 @@
# ext-template

GitHub template repo for new Avocado extensions. **Use this template** → then work
through the checklist below.

## New-extension checklist

1. Rename the repo `ext-<name>` (or `bsp-<board>`).
2. `avocado.yaml` — rename the extension key to `avocado-ext-<name>`, fill in
`summary`/`description`, set `supported_targets` (and `default_target` for a BSP),
list your `packages`. Leave the `sdk.image` line alone.
3. `.github/workflows/test.yml` — set the matrix `target` to something the extension
actually supports (`qemux86-64` is fine for target-agnostic extensions).
4. `.github/workflows/release.yml` — same, plus add matrix rows for every feed you
publish into.
5. `CHANGELOG.md` — replace the placeholder `0.1.0` entry.
6. Delete this section from the README and describe the extension instead (see
"Using this extension" below — keep that part).
7. Repo secrets `AVOCADO_CONNECT_TOKEN` and `AVOCADO_CONNECT_ORG` must be set (org-level
secrets cover this if the repo is in `avocado-linux`).

Release: tag the commit with the exact `avocado.yaml` version, e.g. `git tag 0.1.0 && git push --tags`.

## Conventions

- **SDK image is release-scoped, not channel-scoped.**
`docker.io/avocadolinux/sdk:{{ env.AVOCADO_DISTRO_RELEASE }}` → `avocadolinux/sdk:2026`
on a 2026 CI leg, `avocadolinux/sdk:2024` on a 2024 one. Do not append
`-{{ env.AVOCADO_DISTRO_CHANNEL }}` — there is no such tag on any release. The channel
selects the *package feed*; the image tag is per-release only.
- **CI comes from `avocado-linux/actions@v1`**, pinned. The matrix lives in the caller so
each repo owns its own target/feed combinations.
- **Feed today is `2024`/`edge-next`.** `avocado-linux/actions@v1` *defaults* to
`2026`/`edge`, but the 2026 feed currently publishes only `jetson-agx-thor`, so the
workflows here pass 2024 explicitly. Move a target to 2026 as it lands there.

## Using this extension

`ext-template` is an [Avocado](https://avocadolinux.org) extension — a reusable fragment of
build- and runtime-configuration that you compose into your own Avocado project. To use it,
declare it as a package-sourced extension in your `avocado.yaml` and add it to a runtime:

```yaml
extensions:
avocado-ext-template:
source:
type: package
version: "*" # or pin an exact version

runtimes:
my-runtime:
extensions:
- avocado-ext-template
```
# ext-container-agent-dev

`avocado-ext-container-agent-dev` - the device side of Container Dev Mode.

The agent holds a control WebSocket open to the host CLI, proxies image pulls
from the host's registry over a bootstrap-delivered pinned CA, and hot-reloads
the target container when a sync lands. It is what makes `avocado container dev`
transfer only the changed layer instead of a whole image.

**Development only.** This extension exists so it can be composed into a dev
runtime and left out of production. The `-dev` suffix is the gate. Do not ship it
on a production device.

## Layout

| Path | What it is |
|---|---|
| `agent/` | the Rust crate, cross-compiled at package time |
| `cad-compile.sh` | resolves the target triple and builds the crate |
| `cad-install.sh` | stages the built binary into the extension sysroot |
| `cad-clean.sh` | clears the build directory |
| `overlay/` | the `container-agent-dev` path and service units |
| `avocado.yaml` | extension manifest |

## Requires a container engine

The agent execs the engine CLI as its own child on every sync, so a runtime
without the `docker` extension gives it nothing to do. That dependency is stated
rather than declared: avocado-cli parses an inter-extension dependency and logs
it without installing anything, so declaring it would read as a guarantee and
deliver none. Compose both into the runtime yourself. The agent's startup
preflight is what makes a missing engine fail loudly rather than silently.

Then install and build:
## Building locally

```sh
avocado install # fetches + installs the SDK, extensions and runtime deps from your config
avocado build # builds the SDK compile steps, extensions and runtime images
The SDK image tag is release-scoped and comes from the environment, so export it
before building:

```
AVOCADO_DISTRO_RELEASE=2024 avocado ext install -t qemux86-64 avocado-ext-container-agent-dev
AVOCADO_DISTRO_RELEASE=2024 avocado ext build -t qemux86-64 avocado-ext-container-agent-dev
```

`avocado install` pulls the extension from your target's package feed and merges its
config into your project; `avocado build` then produces the runtime.
Two things that will otherwise cost you time:

- `avocado` runs its SDK container with a TTY, so a build launched without one
fails with `cannot attach stdin to a TTY-enabled container`. Wrap it in
`script -qefc '<cmd>' /dev/null` when running from CI or a background shell.
- dnf prompts for confirmation and blocks; `--no-tui` does not suppress it. Pass
`--dnf-arg -y`.

## Supported targets

`avocado.yaml` lists them explicitly rather than using `'*'`. A target belongs
there once it has produced an installable package and the produced binary has
been seen to exec on that architecture. The release matrix in
`.github/workflows/release.yml` should carry one row per declared target.

## Releasing

Tag the version in `avocado.yaml`. The release workflow guards that the tag and
the manifest version match, packages one leg per matrix row, and publishes each
to the feed derived from that row's distro release and channel.

Bump `release:` whenever the packaged payload changes without a version change.
An unchanged version-release identity means the package manager never delivers
the new payload to a device that already has the extension installed, and both
the build and the install report success anyway.
3 changes: 3 additions & 0 deletions agent/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
/target
# Cross-compilation config written by cad-compile.sh at build time.
/.cargo/
Loading