buildctl¶

⚠ Redesigned (2026-07-05). The implementation this section documents was removed and the tool redesigned — see the CLI overview for the new surface and ADR-0031 for the decision. Headlines: no pure-Go pipeline (assembly delegated, container on macOS), backends docker/mkosi/shell, never auto-detected, signing inside build, local-only index init/add/update instead of publish. The tutorials and reference pages below describe the old tool and await rewrite.

buildctl builds signed DDI packages for Offline Lab and any systemd-based host that runs portable services. It takes a project directory with a package.yaml and a build backend, and produces a .raw image with dm-verity integrity and a PKCS7 signature that systemd verifies natively at attach time.

• GPT layout per the Discoverable Partitions Specification: root + verity + signature partitions, with roothash-bound partition GUIDs.

Where to start¶

New to buildctl? Work through Build your first package. It scaffolds, builds, and validates a complete DDI from scratch.

Tutorials¶

• Build your first package: end-to-end walkthrough from buildctl new to a verified image.

How-to guides¶

Task-focused recipes. Assume you have buildctl installed and a signing key.

• Build a package
• Cross-compile for a different architecture
• Customize the rootfs (skeleton + .buildignore)
• Validate a built DDI
• Publish to a repository

Reference¶

• Command reference
• package.yaml fields
• Build backends
• DDI output and metadata
• Repository index format

Explanation¶

• Architecture and build pipeline
• Signing and trust model

Related projects¶

buildctl is one tool in the Offline Lab ecosystem. It produces packages that appctl installs and manages on devices. For the package format specification, repository model, security model, and the conceptual build pipeline, see the Offline Lab documentation.