Berry Wiki

Mkosi

Properties2
tagsai, sandboxing
aliasesMkosi

9 min read

Mkosi

Checked: 2026-07-14

Project Summary

mkosi builds customized Linux operating-system images from short configuration files. It wraps distribution package managers such as dnf, apt, pacman, and zypper, then can open or boot the result as a container or virtual machine.

  • Maintainer: The systemd project
  • Implementation: Python 3.9+
  • License: LGPL-2.1-or-later for the Python project package
  • Main role: Reproducible OS-image builder and runner
  • Agent focus: None; it is general Linux infrastructure

Problem Solved

Building a repeatable Linux image normally requires hand-written package-manager, partitioning, bootloader, signing, and launch scripts. mkosi combines these into one configuration-driven workflow.

For coding-agent isolation, mkosi can create an expendable image and run it with QEMU. However, this is a use of its general VM features, not a dedicated coding-agent product.

How It Works

  1. Read mkosi.conf, configuration drop-ins, profiles, and optional subimage definitions.
  2. Install a selected Linux distribution into a new root tree through its native package manager.
  3. Add packages, files, scripts, users, boot support, signing, encryption, and image layout requested by configuration.
  4. Produce an output such as a GPT disk image, directory tree, tar archive, CPIO archive, or Unified Kernel Image.
  5. Run the result through one of several paths:
    • shell: Enter it through systemd-nspawn without booting its init system.
    • boot: Boot systemd inside a systemd-nspawn container.
    • vm: Boot with QEMU by default, or systemd-vmspawn when selected.
  6. Optionally run ephemerally on a temporary snapshot that is removed at exit.

Reflink-capable file systems such as Btrfs and XFS make temporary copies faster through copy-on-write storage.

Security And Isolation Boundary

The boundary depends on the chosen runner:

  • QEMU vm: Hardware-assisted virtual-machine boundary when KVM is available. This is the strongest mkosi execution option for untrusted code.
  • systemd-vmspawn: Virtual-machine boundary using systemd’s VM launcher.
  • systemd-nspawn shell or boot: Container boundary that shares the host kernel. It is lighter but not equivalent to a VM against kernel escape.
  • mkosi-sandbox: The official manual explicitly says this helper is not designed as a security boundary. It isolates build commands from host state, not hostile code from the host.

mkosi does not present a coding-agent-specific threat model, hardened default profile, host protection policy, or guarantee that a generated image is safe. Security depends on image configuration, runtime choice, host kernel, QEMU/systemd versions, mounted paths, credentials, network settings, and launch arguments.

Supported Platforms And Agents

Hosts

  • Host operating system: Linux only.
  • Minimum host capabilities: Linux kernel 5.12 features, systemd 254+ for bootable disk-image builds, Python 3.9+, package-manager tooling, and unrestricted user namespaces.
  • KVM: Recommended for practical VM speed; access may need host configuration on Debian, Ubuntu, and Kali.
  • Cross-distribution builds: Possible when the host has the target package manager or uses a recommended mkosi tools tree.

Guest Distributions

Officially documented targets include Fedora, Debian, Kali, Ubuntu, Arch, openSUSE, Mageia, CentOS, RHEL, RHEL UBI, OpenMandriva, Rocky, Alma, Azure Linux, and postmarketOS. A custom/prebuilt root-file-system path is also available.

Coding Agents

  • Named integrations: None documented for Claude Code, Codex, or other coding agents.
  • Usable pattern: Install an agent in the image, mount or copy source into it, boot a VM, and connect through its console or SSH.
  • Automation layer: The user must build agent startup, worktree, lifecycle, cleanup, approval, and result-extraction behavior around mkosi.

Workflow And Setup

Install mkosi from a Linux distribution package, upstream distribution repositories, pipx, a Python virtual environment, or its repository shim. The README recommends version 16 or newer and recommends a tools tree for current dependency handling.

A normal workflow is:

  1. Initialize or write project configuration.
  2. Review the resolved configuration with summary or cat-config.
  3. Build the image.
  4. Boot it with vm for a VM boundary, or use boot/shell for a container.
  5. Connect through mkosi ssh when SSH support and keys are configured.
  6. Use ephemeral mode when runtime changes should disappear after exit.

mkosi genkey can generate the key and certificate used by mkosi ssh. Local-only configuration has separate override files intended for version-control exclusion.

Network And Credential Handling

Network

Runtime network modes are:

  • user: User-mode networking; the default.
  • interface: A host-to-image virtual interface: veth for containers and TAP for VMs.
  • none: No runtime network configured by mkosi.

Build scripts run without network access by default unless WithNetwork=yes is set. Package installation still needs repositories. Proxy URL, exclusion, server-certificate, client-certificate, and client-key settings are supported for compatible tools.

mkosi does not document a built-in destination or hostname allow-list like Clawk. Users must add firewall, proxy, or QEMU/network policy themselves.

Credentials

  • Runtime credentials: Credentials= accepts key/value data, files, executable credential providers, or directories and passes the results to systemd-nspawn or the VM through systemd’s credential mechanism.
  • SSH: SshKey= and SshCertificate= support mkosi ssh; key material may be generated with mkosi genkey.
  • Credential directory: mkosi.credentials can supply additional credentials.
  • Risk: mkosi passes credentials but does not provide a coding-agent-aware broker, service allow-list, automatic token rotation, or protection from an internet-enabled guest that reads and sends a credential elsewhere.
  • Host exposure: RuntimeTrees= and BindUser= can expose host directories. BindUser= is disabled by default. Any writable mount expands the damage available to an untrusted guest.

Strengths

  • Mature image builder: Ten years of history, thousands of commits, regular releases, and systemd-project maintenance.
  • Broad distribution support: One model covers many common Linux families.
  • Multiple output types: Disk, directory, archive, boot image, and extension use cases.
  • Flexible runtime: Container for speed or VM for a stronger boundary.
  • Ephemeral execution: Temporary runtime snapshots can discard changes automatically.
  • Reproducible configuration: Composable files, profiles, drop-ins, and subimages work well in version control.
  • Native systemd features: Credentials, SSH over VM sockets, systemd-repart, Verity, Unified Kernel Images, encryption, and measured-boot-related workflows.
  • Controlled build hooks: Custom build scripts have networking disabled by default.
  • Active testing: Unit, type, lint, installation, and full build-and-boot integration test paths are documented.

Limits And Risks

  • Not an agent sandbox product: No agent CLI, policy layer, task lifecycle, worktree management, result collection, or agent-specific defaults.
  • Easy boundary confusion: shell, boot, vm, and mkosi-sandbox have different security properties. The name “sandbox” does not mean hostile-code containment.
  • Linux-only host: It does not directly solve macOS or Windows local-agent isolation.
  • Complex surface: The manual has many settings and assumes Linux, systemd, image, and boot knowledge.
  • Host requirements: User-namespace restrictions can break operation and may require lowering host restrictions.
  • No built-in internet allow-list: Network modes are broad; fine destination control is external work.
  • Mount risk: Source mounts and bound home directories connect the guest to host data and can weaken disposability.
  • Credential risk: Passing a secret is supported, but limiting where that secret may be used is not.
  • Root/privilege details vary: Unprivileged operation depends on host user namespaces and systemd services; interface networking, device access, and some image operations can require host setup or privilege.
  • VM ergonomics require assembly: Users must choose image packages, SSH, agent installation, mounts, networks, and cleanup policy.
  • Configuration compatibility: The v26 release changed option parsing and warns rather than fails on unknown settings unless MinimumVersion= is used.

Project Activity And Current Maturity

  • Repository created: 2016-07-13
  • Latest repository push when checked: 2026-07-13
  • Repository signal: 6,626 commits displayed, about 1,954 stars, 438 forks, and roughly 100 combined open issues and pull requests in GitHub metadata
  • Latest stable release: v26, released 2025-12-17 with a verified tag
  • Current work: The main branch remained active one day before this review.
  • Maturity assessment: Mature and actively maintained as an OS-image tool. Its building blocks are production-grade enough for serious Linux image workflows, but a safe coding-agent platform built on it remains a separate engineering project.

Best Fit

mkosi fits:

  • Linux and systemd teams that want reproducible custom OS images;
  • projects that need the same image for local testing, continuous integration, containers, VMs, initrds, or boot media;
  • advanced users willing to assemble a coding-agent VM workflow themselves;
  • users who need multiple guest distributions or security features such as Verity, encryption, and signed boot artifacts.

It is a weak fit for someone seeking a turnkey run agent safely command, simple per-project network policy, automatic credential brokering, or macOS support.

Comparison-Relevant Facts

FactMkosi
Primary purposeBuild bespoke Linux OS images
Agent integrationNone
Strongest isolationQEMU or systemd-vmspawn VM
Lightweight modesystemd-nspawn container
Helper sandboxExplicitly not a security boundary
Host supportLinux
Guest supportMany Linux distributions
Storage/disposalRebuilt images; optional ephemeral runtime snapshots
Default runtime networkUser-mode networking
Network off switchYes, RuntimeNetwork=none
Destination allow-listNo built-in agent-oriented allow-list
CredentialsGeneric systemd runtime credentials plus SSH key/certificate support
Source accessConfigurable runtime mounts; user home bind disabled by default
SSHBuilt-in mkosi ssh for properly configured VMs
Rootless operationPossible where unrestricted user namespaces and required systemd services are available
ConfigurationDeclarative files, profiles, drop-ins, subimages, and command flags
LicenseLGPL-2.1-or-later

Hacker News Comment Context

A commenter in the Clawk thread said they use mkosi and called it “brilliant,” while summarizing it as a front for systemd-nspawn. They reported friction mounting a directory when using shell instead of a fully booted image: the mount must be configured in the .nspawn settings.

That comment describes one mkosi path but is incomplete. Official documentation shows that mkosi also builds many image formats and can boot a full QEMU or systemd-vmspawn VM. For Clawk-style hostile-agent isolation, the VM path is the relevant comparison; systemd-nspawn shares the host kernel, and mkosi-sandbox explicitly is not a security boundary.

The comment’s mount complaint aligns with the documentation: NSpawnSettings= or mkosi.nspawn configures nspawn, while current mkosi also documents RuntimeTrees= for mounting directories into containers or VMs. Whether RuntimeTrees= fully removes the commenter’s exact shell friction was not verified in a live run.

Unknowns

  • Agent hardening profile: No official coding-agent threat model or recommended locked-down profile was found.
  • Fine network policy: No official built-in hostname allow-list or agent egress broker was found.
  • Secret lifetime: Exact in-guest visibility and cleanup depend on the systemd credential consumer and image configuration; mkosi alone does not guarantee safe use.
  • Cross-architecture behavior: The supported combinations and emulation performance vary by host, target distribution, and installed tools.
  • HN mount issue today: The report is current discussion evidence, but its exact configuration was not provided and was not reproduced.

Sources

Graph View