# corail documentation, plain text # Introduction corail is a small, daemonless container engine for Linux and macOS (Intel and Silicon). ## What is corail? corail runs containers from OCI images. It pulls from any registry, unpacks the layers, and starts your process. Each corail command does its work and exits. On Linux it is one static binary. Containers run rootless by default, in their own namespaces and cgroups, so you do not need sudo to try it. On macOS (Intel and Silicon) the same commands run Linux images in a microVM. One VM stays up per store, so a later corail ps sees the containers a previous corail run started. OCI registry any registry, image layers pull corail one static binary. Pulls, unpacks, starts, then exits. Linux namespaces and cgroups, rootless or macOS one microVM per store. The same binary runs inside it. start capsule your process, one running container On Linux, corail starts the capsule on the host. On macOS, it starts the capsule inside a Linux microVM that stays up for that store. ## The tools - corail: the engine. Pull images, run, stop and inspect containers (called capsules). - coraild: the control plane. It keeps groups of capsules, called atolls, running as described in a reef.json. - recify: the command-line client for coraild, in the spirit of kubectl. - sonar: a terminal view of a running atoll. ## Vocabulary - capsule: one running container. - atoll: a group of capsules that share a network namespace and are scheduled together. - reef.json: the file that describes an atoll. The commands and flags follow Docker's, so corail run, ps, logs, exec, stop and rm behave the way you expect. ## Platforms - Linux (x86_64, aarch64): runs containers natively. - macOS (Intel and Silicon): runs Linux images in a microVM. - Windows: not planned. ## Where to go next - Commands: every corail subcommand and flag. - Reference: the reef.json format, and coraild and recify. --- # Install Four binaries: corail, coraild, recify and sonar. ## Linux, one line $ curl -fsS https://www.coraild.com/install | bash The release archives hold static builds of all four. Read the script before you pipe it to a shell. ## Build from source You need Zig 0.16 (the version is pinned in build.zig.zon) and just. $ git clone git@github.com:dbrrt/zocker.git && cd zocker $ just build # zig build -Doptimize=ReleaseFast $ ls zig-out/bin corail coraild recify sonar Put the four binaries in one directory on your PATH. sonar looks for corail next to itself first. $ corail version corail 0.0.1 (unknown) ## Rootless prerequisites corail run needs no sudo. It needs a Linux kernel with user namespaces, cgroup v2 and overlayfs, plus newuidmap and newgidmap (the uidmap package) and an entry for your user in /etc/subuid and /etc/subgid. Most distributions set this up for normal users. Resource limits (--memory, --cpus, --pids-limit) need a delegated cgroup subtree. Where there is none, the container still runs, without limits. ## Ubuntu 23.10 and later: AppArmor Without subuid ranges, corail maps only your own uid, and Ubuntu 23.10+ (kernel.apparmor_restrict_unprivileged_userns=1) blocks that. If you skip the step below, corail run exits 1 and prints this first line, followed by the three ways out: corail: cannot create a usable user namespace (EPERM). The fix is one time and needs sudo: $ just install-apparmor installing AppArmor profile for /path/to/zig-out/bin/corail done — corail now runs rootless The profile attaches to that exact binary path. Run it again if you move the binary. It carries only the userns, rule. ## macOS On Intel and Silicon Macs corail runs the Linux engine in a microVM, and recify up starts the control plane in a Linux guest. Install from the same archives; see Introduction for how it works. ## Check it works $ corail run --rm alpine -- echo hi hi The first run pulls alpine. Next: run a container. --- # Run a container A container is a capsule. Every command below was run on Linux, rootless, and its output is pasted as printed. ## Run with limits and a volume $ corail run --rm --memory 64m --cpus 1 --pids-limit 64 -v /srv/data:/data:ro alpine -- cat /data/greeting.txt hello --rm deletes the container when it exits. -v host:ctr[:ro] bind mounts a directory. --memory takes a byte count or a k, m or g suffix. The target is an image (pulled if it is not cached) or a path to a rootfs directory. A command after -- replaces the image's default Cmd. The full flag list is on Commands. The exit status of the container is the exit status of corail run: $ corail run --rm alpine -- sh -c 'exit 3'; echo $? 3 ## Run in the background, then manage it $ corail run -d --name web --memory 64m alpine -- sh -c 'echo started; sleep 300' web $ corail ps ID PID STATUS COMMAND web 47722 running sh $ corail logs web started $ corail exec web -- uname -a Linux web 6.17.0-35-generic #35~24.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue May 26 19:30:42 UTC 2 x86_64 Linux $ corail stop web web $ corail ps ID PID STATUS COMMAND web 47722 exited sh $ corail rm web web stop sends the stop signal and waits up to --grace seconds before killing. A stopped container stays in ps as exited until rm. ## Images $ corail pull alpine corail: pulled library/alpine:latest $ corail images REPOSITORY TAG LAYERS library/alpine latest 1 $ corail prune corail: pruned 2 blob(s), reclaimed 3.7 MiB $ corail rmi alpine library/alpine:latest prune deletes cached download blobs and keeps extracted layers, so images keep running from cache. rmi removes the image record. ## Rootless limits Without root, --net supports host (the default) and none. bridge and -p need root. Next: run a group of containers. --- # Run an atoll An atoll is a group of capsules that share a network namespace, described by a reef.json. ## Your first atoll This is examples/web/reef.json in the repository. It applies unchanged. { "name": "web", "restart": "Always", "capsules": [ { "name": "app", "image": "alpine:latest", "cmd": ["sh", "-c", "while true; do nc -l -p 8080; done"], "probe": { "exec": ["sh", "-c", "echo x | nc -w 1 127.0.0.1 8080"], "period_seconds": 2, "failure_threshold": 3 } }, { "name": "sidecar", "image": "alpine:latest", "cmd": ["sleep", "300"] } ] } Start the daemon, apply the file, and watch it settle. The output below is what a run printed. $ coraild & $ recify apply -f examples/web/reef.json atoll/web applied $ recify get atolls NAME READY STATUS RESTARTS AGE web 2/2 Running 0 6s $ recify describe atoll web Name: web Namespace: default Phase: Running Restart: Always Net: none Capsules: app: Image: alpine:latest State: running Ready: true Restarts: 0 sidecar: Image: alpine:latest State: running Ready: true Restarts: 0 Events: 6s Adopted atoll accepted 6s Started at-web-app 6s Started at-web-sidecar $ recify exec web -c sidecar -- echo hi hi $ recify delete atoll web atoll/web deleted The two capsules reach each other over loopback. coraild runs app's probe every 2 s. Three failures in a row kill and restart the capsule. sonar shows the same table live. ## Fields Unknown fields are ignored. recify apply rejects a file that breaks a rule below and prints the reason. ### Atoll Field | Type | Default | Meaning | name | string | required | The atoll name. Only a-z A-Z 0-9 - _ . are allowed. | namespace | string | "default" | Label-style namespace. recify get atolls shows "default" unless you pass -n. | restart | Always | Never | OnFailure | "Always" | Restart policy. Repeated crashes back off 1 s, 2 s, 4 s, up to 300 s. | net | none | host | bridge | "none" | corail run --net. Capsules of one atoll share one network namespace. | publish | string[] "host:capsule" | [] | corail run -p. Only with net "bridge", which needs root. | termination_grace_period_seconds | number | 5 | corail stop --grace. | volumes | Volume[] | [] | Named volumes, mounted by volume_mounts. | init_capsules | Capsule[] | [] | Run to completion before the capsules start. Names must differ from capsule names. | capsules | Capsule[] | required | At least one. | ### Capsule Field | Type | Default | Meaning | name | string | required | Unique inside the atoll. The corail id is at--. | image | string | required | Any registry reference, pulled if not cached. | cmd | string[] | image Cmd | The part after -- in corail run. The image Entrypoint still runs. | env | string[] "K=V" | [] | corail run -e. | secret_env | string[] "K=V" | [] | Written to a 0600 file and passed as -e, so the value is not in the process list. | liveness | Probe | none | Failing past failure_threshold kills and restarts the capsule. | probe | Probe | none | The older name of liveness. liveness wins when both are set. | readiness | Probe | none | Gates the READY column. | startup | Probe | none | Runs first, for slow starters. | volume_mounts | {name, mount_path, read_only}[] | [] | corail run -v. mount_path must be absolute and name must be a declared volume. | resources | {memory, cpus, pids} | {} | corail run --memory, --cpus, --pids-limit. | ### Probe Field | Type | Default | Meaning | exec | string[] | — | Command run inside the capsule. Exit 0 is healthy. | tcp | port | — | TCP connect to that port on the capsule loopback. | http_port, http_path | port, string | —, "/" | HTTP GET on the capsule loopback. | period_seconds | number > 0 | 10 | Seconds between probes. | failure_threshold | number | 3 | Consecutive failures before the probe fails. | initial_delay_seconds | number | 0 | Wait before the first probe. | ### Volume Field | Type | Default | Meaning | name | string | required | A safe path component. Unique in the atoll. | host_path | string | "" | A host directory. | files | {path, content}[] | [] | Files the daemon writes for you. path is relative with no "..". A volume needs host_path or files. | Also in YAML: recify apply -f reef.yaml takes the same fields. --- # sonar A terminal view of a running coraild, in the spirit of k9s. Run sonar while coraild is up. It talks to the same unix socket recify uses, refreshes every second, and shows a banner and retries if the daemon goes away. ## The atolls view Enter drills into an atoll's capsules, l shows a capsule's logs, d describes it, and Esc goes back. sonar · atolls (3) · /var/lib/coraild ──────────────────────────────────────────────────────────────────── NAME READY STATUS RESTARTS AGE ❯ web 2/2 Running 3 12m batch 0/1 Failed 1 2h cache 1/1 Running 0 4d ──────────────────────────────────────────────────────────────────── ↑↓/jk · enter capsules · l logs · d describe · / filter · s sort · q ## Keys This table is read from docs/SONAR.md when the site is built. Key | Action | ↑/k, ↓/j, pgup/pgdn | move selection / scroll | g, G | top / bottom | enter | drill in (atoll → capsules → logs) | esc | back | l | logs (selected capsule) | f | toggle follow (logs view) | d | describe (pretty JSON) | s (capsules view) | shell into the selected capsule (corail exec -it sh) | ctrl-d | delete atoll (confirmation dialog) | R | restart atoll (confirmation dialog) | / | filter atolls by name | s / S (atolls view) | cycle sort column / reverse direction | : | command bar (:atolls, :q) | ? | help overlay | r | refresh now | q / ctrl-c | quit | --- # Commands Run corail with no arguments for the full usage text. These commands are the same on Linux and on macOS (Intel and Silicon). On macOS they run the Linux engine inside the microVM. ## Subcommands - corail run [flags] [-- cmd args…]: start a container. - corail ps: list running containers. - corail stop [--grace SECONDS] : stop a container. - corail rm : delete a container. - corail logs : print a container's output. - corail exec -- cmd args…: run a command inside a container. - corail pull [--platform os/arch] [:tag]: fetch an image. - corail images: list cached images. - corail rmi [:tag]: remove an image. - corail prune: delete cached blobs; keeps extracted layers. - corail dial : connect stdio to a TCP port on the container's loopback. - corail version: print the version. ## corail run is an image reference such as alpine or nginx:1.27 (pulled if not cached), or a path to an extracted rootfs directory starting with /, ./ or ../. A command after -- replaces the image's default Cmd. - -d: run in the background. - --rm: delete the container when it exits. - --name NAME, --hostname NAME: names. - -e K=V: environment variable, repeatable. - --label K=V: label, repeatable. - -v host:ctr[:ro]: bind mount, repeatable. - --memory BYTES: memory limit; accepts k, m, g suffixes, e.g. 256m. - --cpus N, --pids-limit N: CPU and process limits. - --net host|none|bridge|capsule:ID: network mode. Rootless supports host (default) and none; bridge and -p need root. - -p host:ctr: publish a port, repeatable (root only). --- # Reference The reef.json format, and the tools that run it. ## reef.json A reef.json describes one atoll: a group of capsules that share a network namespace. - name: the atoll's name. - restart: restart policy, Always or Never. Repeated crashes back off. - capsules: the list of capsules. - name, image, cmd: what to run. - probe.exec: a command run inside the capsule as a liveness check. - probe.period_seconds, probe.failure_threshold: how often to probe, and how many failures kill and restart the capsule. Every field with its type, default and flag is on Run an atoll. Full example, from examples/web: { "name": "web", "restart": "Always", "capsules": [ { "name": "app", "image": "alpine:latest", "cmd": ["sh", "-c", "while true; do nc -l -p 8080; done"], "probe": { "exec": ["sh", "-c", "echo x | nc -w 1 127.0.0.1 8080"], "period_seconds": 2, "failure_threshold": 3 } }, { "name": "sidecar", "image": "alpine:latest", "cmd": ["sleep", "300"] } ] } ## coraild The control plane. It watches the desired state, starts and supervises capsules, and serves a JSON API on a unix socket at $CORAILD_ROOT/coraild.sock. Design and status: CORAILD.md. ## recify The client for coraild, in the spirit of kubectl. On Linux, start the daemon, then use it: $ coraild & $ recify apply -f reef.json $ recify get atolls $ recify describe web $ recify logs web $ recify delete web On macOS (Intel and Silicon), recify up starts a Linux guest through Docker or Apple's container tool. recify down stops it. apply, get, describe, logs and delete are the same. ## sonar A terminal view of a running atoll. Key map: SONAR.md. --- # CLI usage The exact text each binary prints when you run it with no arguments. Generated from the sources when the site is built. If a flag is not here, the binary does not have it. ## corail corail — a Docker clone in Zig Usage: corail version corail run [--memory BYTES] [--pids-limit N] [--cpus N] [--name NAME] [--hostname NAME] [-d] [-i] [-t] [--rm] [--cap-add CAP]... [--cap-drop CAP]... [-e K=V]... [--label K=V]... [--seccomp-trace] [-v host:ctr[:ro]]... [--net host|none|bridge|capsule:ID] [-p h:c]... [-- [args...]] corail ps corail stop [--grace SECONDS] corail rm corail logs corail attach (terminal of a capsule started with run -d -t) corail pull [--platform os/arch] [:tag] corail images corail rmi [:tag] corail prune (delete cached blobs and unfinished capsule directories; keeps extracted layers) corail exec [-it] [--user user[:group]] -- [args...] corail net repair (root: set the bridge up again, with its NAT rules) corail dial (stdio ↔ capsule loopback TCP) corail run-raw -- [args...] (Phase 1: no cgroups/state) corail x86-selftest (VM only, CORAIL_X86=emu) is an image reference (e.g. alpine, nginx:1.27 — pulled automatically if not cached yet) or a path to an already-extracted rootfs directory (must start with /, ./, or ../). is optional for image targets: it replaces the image's default Cmd; its Entrypoint (if any) still runs. Runs rootless via user namespaces (no sudo needed); as root it uses plain namespaces. --memory accepts a byte count or a k/m/g suffix, e.g. --memory 256m. --net bridge (with -p port mapping) requires root; rootless supports --net host (default) and --net none. ## recify recify — control the coraild control plane Usage: recify apply [-f ] (default: ./reef.json) recify get atolls|at [-n ns] [-A] [-o json|name] [-w] recify get atoll recify describe atoll recify delete atoll recify rm recify logs [capsule] recify exec [-c capsule] -- ... recify port-forward : [-c capsule] recify run --image [-e K=V]... [--restart Always|Never|OnFailure] [--net none|host|bridge] [-n ns] -- [cmd...] recify up | down | status recify version recify completion bash|zsh sonar has no flags; see its keys. --- # Numbers Every figure on this site is read from bench/site-numbers.json. Each row names the command that produced it. ## Linux bench/linux-three-way.sh, p16s, Core Ultra 7 165H, Linux 6.17, Docker 29.1.3, Podman 4.9.3 rootless, 2026-11-07. Source: docs/PERFORMANCE.md. Image | Metric | corail | Docker | Podman | alpine | warm run --rm /bin/true, median of 20 | 6 ms | 214 ms | 110 ms | alpine | exec /bin/true, median of 20 | 2 ms | 53 ms | 105 ms | alpine | host footprint of 50 idle sleeps | 54 MB | 1.2 GB | 107 MB | busybox | warm run --rm /bin/true, median of 20 | 7 ms | 289 ms | 147 ms | busybox | exec /bin/true, median of 20 | 4 ms | 69 ms | 119 ms | busybox | host footprint of 50 idle sleeps | 53 MB | 1.2 GB | 106 MB | debian | warm run --rm /bin/true, median of 20 | 6 ms | 265 ms | 135 ms | debian | exec /bin/true, median of 20 | 2 ms | 61 ms | 116 ms | debian | host footprint of 50 idle sleeps | 53 MB | 1.2 GB | 106 MB | ## macOS bench/mac-image-start.py, bench/mac-image-rest.py, bench/mac-image-idle.py, Apple M4 Pro, macOS 26.6.2, Docker Desktop 4.98.0 (engine 29.9.2), Podman 6.1.4 applehv, 4 vCPU, 2 GiB, 2026-11-16. Source: docs/PERFORMANCE.md, section macOS three-way, refreshed 2026-11-16. Image | Metric | corail | Docker | Podman | alpine | warm run --rm /bin/true, median of 20 | 5.4 ms | 132 ms | 152 ms | alpine | exec /bin/true, median of 20 | 5.2 ms | 33 ms | 115 ms | alpine | host footprint of 50 idle sleeps | 196 MB | 1.5 GB | 1.3 GB | busybox | warm run --rm /bin/true, median of 20 | 5.2 ms | 140 ms | 155 ms | busybox | exec /bin/true, median of 20 | 4.2 ms | 31 ms | 114 ms | busybox | host footprint of 50 idle sleeps | 190 MB | 1.4 GB | 1.3 GB | debian | warm run --rm /bin/true, median of 20 | 6.6 ms | 145 ms | 159 ms | debian | exec /bin/true, median of 20 | 4.3 ms | 31 ms | 113 ms | debian | host footprint of 50 idle sleeps | 340 MB | 1.4 GB | 1.3 GB | ## Targets and the control plane A target is a target, not a result. The measured column is from just bench-check with SITE_NUMBERS=1; a row says "not re-recorded" when that run has no figure for it. Metric | Measured | Target | Command, commit | warm run --rm /bin/true, median of 10 | 5 ms | ≤ 9 ms | just bench-check (run --rm alpine -- /bin/true, median of 10), p16s d21ab26 | exec /bin/true, median of 10 | 2 ms | ≤ 15 ms (guard) | just bench-check (exec /bin/true, median of 10), p16s d21ab26 | recify apply to Running | 6 ms | ≤ 50 ms, guarded | bench/coraild.sh, p16s d21ab26 | kill to recovered | 8 ms | ≤ 300 ms, guarded | bench/coraild.sh, p16s d21ab26 | coraild RSS at 50 atolls | 3.6 MB | < 16 MB | bench/coraild.sh, p16s d21ab26 | The comparison against Kubernetes (bench/vs-k8s.sh) has not been run for this site, so no Kubernetes figure appears here. ## How we measure - Tools are sampled interleaved, and the tool that goes first rotates each round. - Three warm-up rounds are discarded. Latency rows use at least 20 samples and report the median. - The image is pulled on every side before timing starts. - A verdict needs a paired sign test, |z| ≥ 1.96, with at least 80% agreement (bench/ab-verdict.sh). - Memory is resident size summed over the daemon and each container's supervisor. - A network-bound figure, such as a cold pull, is only an absolute hang guard. It measures the link, not the code. - Rows where corail is worst are flagged as findings, not dropped. Rules in full: bench/results/latest-p16s.md and docs/PERFORMANCE.md.