apple/containerization currently runs containers in per-container VMs on
macOS hosts via Virtualization.framework. This adds a second VMM backend
so the same Swift orchestration layer (LinuxContainer / LinuxPod /
Vminitd gRPC contract) runs on Linux hosts via cloud-hypervisor + KVM.
**CloudHypervisor Swift package** (`Sources/CloudHypervisor/`) — a thin
client for cloud-hypervisor's REST-over-UDS API, layered on
AsyncHTTPClient. Endpoints cover VMM / VM lifecycle / hotplug (disk, fs,
net, vsock, remove-device). Cross-platform (compiles on macOS for unit
tests; consumed at runtime only by the Linux side of Containerization).
**CH backend in Containerization** — one cloud-hypervisor subprocess per
VM, gated behind `#if os(Linux)`. CHVirtualMachineManager /
CHVirtualMachineInstance mirror the VZ shape behind the existing
VirtualMachineManager / VirtualMachineInstance protocol. CHProcess and
VirtiofsdProcess manage the binaries; CHHotplugProvider handles
virtio-blk and virtio-fs runtime hotplug (with one virtiofsd per unique
source-hash tag, refcounted across containers).
**Linux host networking** — BridgeManager brings up a Linux bridge with
an IPv4 subnet and (opt-in via `--enable-nat`) iptables MASQUERADE +
scoped FORWARD rules. LinuxBridgedNetwork enslaves a fresh TAP per
container to the bridge. State is recorded under `/run/containerization`
so `cctl bridge delete` reverses exactly what create did. Bridge
teardown verifies the link kind via sysfs to refuse deleting non-bridge
interfaces.
**cctl run / bridge** — end-to-end Linux container run path (image pull,
ext4 rootfs assembly, VM boot, container exec) plus `cctl bridge
create|delete` for the host network plumbing.
**Build & dist** — `make linux-build` / `make linux-integration` build
and exercise the host side inside an apple/container `--virtualization`
dev container. `make dist-x86_64` produces a deployment tarball (cctl +
cloud-hypervisor + virtiofsd + initfs + kernel) cross-compiled from the
aarch64 dev container; pipeline documented in `docs/x86_64-build.md`.
Static-musl C deps and the Zig cross compiler are pinned by SHA256.
The host orchestrator runs as root. Per-VM runtime state lives under
`/run/containerization/ch/<UUID>` with mode 0700; UDS sockets inside are
bound with mode 0600. Vminitd's gRPC channel inherits that trust
boundary — socket-file perms are the auth.
Sandbox flags are upstream-secure by default. Two per-component opt-outs
exist for the apple/container dev-container case (where the host seccomp
profile SIGSYS-kills CH and virtiofsd):
- `CONTAINERIZATION_NO_CH_SECCOMP=1` — `cloud-hypervisor --seccomp
false`.
- `CONTAINERIZATION_NO_VIRTIOFSD_SANDBOX=1` — `virtiofsd --sandbox
none`. Each emits a one-shot `logger.warning` at process start. Legacy
alias `CONTAINERIZATION_RELAXED_SANDBOX=1` flips both. cctl spawns both
binaries with `setsid` and a minimal env allowlist (PATH / HOME /
RUST_LOG / RUST_BACKTRACE) so the parent's secrets don't leak to
children.
`make linux-integration` runs the cross-platform integration suite
against a real cloud-hypervisor VM inside the dev container. Linux runs
the cross-platform subset (`process true`/`false`/`echo hi`, virtiofs
round-trip, hotplug); the macOS suite is unchanged.
Signed-off-by: michael_crosby <michael_crosby@apple.com>
Fixes#296
Today the kernel subdirectory is somewhat useless. The dockerfile we had
tried to use an image that isn't actually on ghcr, so everything would
kind of just crap out. This change swaps things so that we build a local
image that has all the bits needed to compile the kernel, and then uses
that image to build the resulting kernel and plop it in the current
working directory. This change does add a reliance on `container` being
installed however, but for folks that need to build a custom kernel this
doesn't seem like too much of an issue to me.
Clarify that container is only supported on macOS 26, and remove
language that implies that it's also designed for macOS 15.
This change also includes a couple of minor textual changes to improve
readability.
## Changes
### README.md
- Fixed grammatical error: "when a process is ran" → "when a process is
run"
- Fixed plural form: "for instruction on" → "for instructions on"
### kernel/README.md
- Fixed numbering sequence: "4. Run `make`" → "3. Run `make`" in build
instructions
### Sources/Containerization/LinuxContainer.swift
- Fixed grammatical error in comment: "The container has ran" → "The
container has run"
Remove Latin abbreviations from the documentation in accordance with the
[Apple Style Guide](https://help.apple.com/applestyleguide/). This
change does not impact any abbreviations used in code comments since
those are not covered by the style guide.
#70 Made it clearer as I wasn't sure if the API allows us to run x64
binaries or also run such Docker images.
---------
Signed-off-by: Aviram Hassan <aviramyhassan@gmail.com>
Co-authored-by: Danny Canter <danny_canter@apple.com>
If we split this out, it'll be easier to point developers at specific
parts for setting up their build environment, versus building and
testing.
Signed-off-by: Eric Ernst <eric_ernst@apple.com>
Some updates to the documentation:
* Replace code-of-conduct with organization one.
* Cleanup `CONTRIBUTING.md`, `README.md` and `SECURITY.md` markdown.
* Remove `.txt` extension from `LICENSE` for consistency across repos.
The first intro sentences don't read very well. This just tries
to create a cohesive section describing the core design.
Signed-off-by: Danny Canter <danny_canter@apple.com>
Michael Crosby