Documentation

Install carrick, learn the CLI, and understand its runtime tracing tools.

Installation

Carrick requires macOS 14 (Sonoma) or later on Apple Silicon. It uses Hypervisor.framework directly — the runtime has no external dependencies and no background services; it is distributed through a Homebrew tap.

$ brew tap carrick-sh/carrick
$ brew install --HEAD carrick

The formula builds carrick from source and ad-hoc codesigns it with the com.apple.security.hypervisor entitlement on install, so it can run Linux guests via Hypervisor.framework.

CLI reference

`carrick run`

Pull an OCI image and execute a command inside it.

$ carrick run [flags] <image> [command] [args...]

Flag	Description
`-t`	Allocate a PTY (interactive mode with real line discipline, Ctrl-C/Ctrl-Z)
`-e KEY=VAL`	Set an environment variable in the guest
`-v /host:/guest[:ro]`	Bind-mount a host directory into the guest (optional read-only)
`-w /path`	Set the working directory inside the guest
`--entrypoint`	Override the image's default entrypoint

Examples:

# Run a one-off command
$ carrick run ubuntu:24.04 /bin/bash -c 'echo hello'
hello

# Interactive shell
$ carrick run -t alpine:latest /bin/sh

# Mount host directory read-only and list it
$ carrick run -v /Users/me/src:/mnt:ro ubuntu:24.04 ls /mnt
Cargo.toml  src  target

# Set environment and working directory
$ carrick run -e RUST_LOG=debug -w /app ubuntu:24.04 env | grep RUST
RUST_LOG=debug

`carrick run-elf`

Execute a local Linux ARM64 ELF binary directly — no OCI pull.

$ carrick run-elf ./my-linux-binary --flag value

Useful when you've already cross-compiled a binary and want to test it without building an image.

`carrick trace`

Instrument guest execution with DTrace USDT probes, exposing the Linux→Darwin syscall translation in real time.

$ sudo carrick trace run alpine:latest /bin/echo hi
[carrick] VM created, vCPU at EL0
[svc #0] sys_write(1, 0x4002c000, 3) → Darwin write(1, "hi\n", 3) = 3
[svc #0] sys_exit_group(0)
[carrick] Process exited, status=0

Requires sudo for DTrace access. Output shows the guest syscall number, arguments, the Darwin call it was translated to, and the return value.

`carrick compat-report`

Scan a Linux binary's syscall usage and report coverage against carrick's implementation.

$ carrick compat-report -- /usr/bin/find / -name '*.so'

Build images & the Docker API

carrick can also build images (carrick build) and expose a Docker-compatible API (carrick serve) — see using carrick with Docker.

Filesystem access

There is no virtual disk or FUSE layer. Guest filesystem operations translate directly to macOS filesystem calls on host paths. Bind mounts (-v) map guest paths to host directories with native performance.

The guest sees a merged filesystem: the OCI image's rootfs plus any bind mounts. Writes go to a scratch overlay — the original image layers are never modified.

Networking

Guest sockets bind directly to host network interfaces. If the guest runs a server on port 8000, you can curl localhost:8000 from the host immediately. No port forwarding configuration is needed.

Linux socket calls (socket, bind, listen, connect, accept) are translated to their Darwin equivalents. epoll is mapped to kqueue. AF_NETLINK is synthesized for programs that probe network configuration.

Crate architecture

Carrick is a Rust workspace — 25 crates, ~194,000 lines. The product path is unchanged; the runtime is now split so the same clean-room Linux-ABI translation can drive several host VMMs and both guest ISAs (see the HAL doc).

carrick-cli              # the `carrick` binary; docker-compatible surface
 └─ carrick-engine       # docker request + image config → RunSpec
     ├─ carrick-image    # OCI pull + local content store
     ├─ carrick-runtime  # Linux behavior: dispatch, VFS, signals, fs, /proc (~99k lines)
     └─ carrick-spec     # vocabulary types: RunSpec, Mount, etc.

# platform-neutral contracts
carrick-hal              # traits-only: trap contract, hypervisor + guest-arch traits
carrick-abi              # Linux syscall numbers, ABI constants, wire structs
carrick-mem              # guest address space: ELF layout, stage-1 page tables
carrick-guest-mem        # guest-memory access trait + syscall frame types
carrick-thread / -signal-core / -timer-core   # thread, signal, timer state
carrick-observability    # compat-reporting support

# host primitives
carrick-host             # Darwin host support (macOS path)
carrick-host-bsd         # BSD-family host layer (macOS / FreeBSD / NetBSD)
carrick-host-linux       # Linux host layer (epoll multiplexer)
carrick-portable         # thin libc shim across host OSes

# VMM backends + shared guest engines
carrick-vmm-hvf          # macOS Hypervisor.framework (mature)
carrick-vmm-kvm          # Linux / KVM
carrick-vmm-bhyve        # FreeBSD / bhyve
carrick-vmm-nvmm         # NetBSD / NVMM
carrick-aarch64          # shared AArch64 engine
carrick-x86              # shared x86_64 engine (KVM / bhyve / NVMM)

Plus carrick-conformance (the differential Docker-oracle harness) and carrick-test-support. The default platform-macos build pulls only carrick-vmm-hvf and the Apple Hypervisor.framework bindings; each non-macOS target selects exactly one platform feature instead.