rund

rund is an experimental containerd shim for running Darwin containers on Darwin.

rund doesn’t offer the usual level of container isolation that is achievable on other OSes due to limited Darwin kernel API.

What rund provides:

• Filesystem isolation via chroot(2)

• Cleanup of container processes using process group

• OCI Runtime Specification compatibility (to the extent it is possible on Darwin)

• Host-network mode only

• bind mounts

You can view a video review of Darwin containers and also read an article. Both were created by Earthly.

Installation and usage

See homebrew-formula repository for end-user instructions.

Development

This section describes development setup for hacking on rund code.

Prerequisites

• Disable System Integrity Protection. SIP doesn’t allow to chroot.

• Install macFUSE or fuse-t

• Install bindfs using build instructions

Usage with containerd

Prerequisite: authenticate to GitHub Package Registry.

Then, run in Terminal:

# Download rund
git clone https://github.com/darwin-containers/rund
cd rund
# Build rund
go build -o bin/ cmd/*.go
cd ..

# Download containerd
git clone https://github.com/darwin-containers/containerd
cd containerd
# Run containerd
sudo go run cmd/containerd/main.go

# Continue from a SEPARATE terminal, without stopping containerd

# Download base image
cd containerd
sudo go run cmd/ctr/main.go image pull ghcr.io/darwin-containers/darwin-jail/ventura:latest

# Aaaand... Run your first Darwin container!

# On Apple Silicon
sudo go run cmd/ctr/main.go run --rm -t --runtime "$(pwd)/../rund/bin/containerd-shim-rund-v1" ghcr.io/darwin-containers/darwin-jail/ventura-arm64:latest my_container /bin/sh -c 'echo "Hello from Darwin container ^_^"'

# On Intel
sudo go run cmd/ctr/main.go run --rm -t --runtime "$(pwd)/../rund/bin/containerd-shim-rund-v1" ghcr.io/darwin-containers/darwin-jail/ventura-i386:latest my_container /bin/sh -c 'echo "Hello from Darwin container ^_^"'

If you want to build image from scratch, see darwin-jail project.

Usage with BuildKit

Perform all the steps from Usage with containerd.

Create /etc/buildkit/buildkitd.toml with the following contents:

[worker.containerd]
runtime = "/path/to/rund/bin/containerd-shim-rund-v1"

Then, from terminal:

# Download BuildKit
git clone https://github.com/darwin-containers/buildkit

# Run BuildKit daemon
cd buildkit
sudo go run ./cmd/buildkitd

# Continue from a SEPARATE terminal, without stopping neither containerd nor buildkitd

# Create Dockerfile
cat << EOF > Dockerfile
FROM ghcr.io/darwin-containers/darwin-jail/ventura:latest
RUN echo "Hello, World!"
EOF

# Aaaaad, build your first Darwin image
sudo go run ./cmd/buildctl build --frontend=dockerfile.v0 --local context=. -local dockerfile=.

Usage with Docker

Perform all the steps from Usage with containerd. You don’t need BuildKit daemon to use Docker on Darwin.

Create /etc/docker/daemon.json with the following contents:

{
  "data-root": "/private/d/",
  "default-runtime": "/path/to/rund/bin/containerd-shim-rund-v1",
  "runtimes": {
    "/path/to/rund/bin/containerd-shim-rund-v1": {
      "runtimeType": "/path/to/rund/bin/containerd-shim-rund-v1"
    }
  }
}

Then, from terminal:

# Download Docker
git clone https://github.com/darwin-containers/moby

# Run Docker daemon
cd moby
cp vendor.mod go.mod
cp vendor.sum go.sum
sudo go run ./cmd/dockerd

# Continue from a SEPARATE terminal, without stopping neither containerd nor dockerd

# Install Docker cli
brew install docker

# Aaaand, run your first Darwin native container
sudo docker run --rm -it ghcr.io/darwin-containers/darwin-jail/ventura:latest echo "Hello from Darwin! ^_^"