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 — no Homebrew dependencies, no background services.

$ curl -fsSL https://carrick.sh | sh

The script downloads the latest release binary and installs it to /usr/local/bin/carrick (or ~/.local/bin if /usr/local/bin isn't writable). It checks for Apple Silicon and verifies kern.hv_support.

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'

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. The primary dependency chain:

carrick-cli
 └─ carrick-engine
     ├─ carrick-image     # OCI pull + layer composition
     ├─ carrick-runtime   # syscall dispatch loop
     └─ carrick-spec      # Linux ABI definitions

carrick-hvf              # HVF trap engine, vCPU cluster, USDT probes
carrick-abi              # syscall number → handler mapping
carrick-mem              # guest memory management, page tables
carrick-host             # host-side Darwin syscall wrappers
carrick-guest-mem        # guest address space utilities