= rund :project-handle: rund :uri-project: https://github.com/macoscontainers/{project-handle} :uri-ci: {uri-project}/actions?query=branch%3Amain :source-highlighter: rouge

image:{uri-project}/workflows/CI/badge.svg?branch=main[GitHub Actions,link={uri-ci}]

rund is an experimental https://containerd.io[containerd] shim for running macOS containers on macOS.

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

What rund provides:

• Filesystem isolation via https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/chroot.2.html[chroot(2)]
• Cleanup of container processes using process group
• OCI Runtime Specification compatibility (to the extent it is possible on macOS)
• Host-network mode only
• bind mounts

You can https://www.youtube.com/watch?v=RS9C_4O_Ohg[view a video review of macOS containers] and also https://earthly.dev/blog/macos-native-containers/[read an article]. Both were created by https://earthly.dev[Earthly].

== Installation and usage

See https://github.com/macOScontainers/homebrew-formula#readme[homebrew-formula] repository for end-user instructions.

== Development

This section describes development setup for hacking on rund code.

=== Prerequisites

• Disable https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection[System Integrity Protection]. SIP https://github.com/containerd/containerd/discussions/5525#discussioncomment-2685649[doesn't allow] to chroot.
• Install https://osxfuse.github.io[macFUSE] or https://www.fuse-t.org[fuse-t]
• Install https://bindfs.org/downloads/[bindfs] using https://github.com/mpartel/bindfs/issues/100#issuecomment-870699085[build instructions]

[[containerd]] === Usage with containerd

Prerequisite: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry[authenticate to GitHub Package Registry].

Then, run in Terminal:

[source,shell]

Download rund

git clone https://github.com/macOScontainers/rund cd rund

Build rund

go build -o bin/ cmd/*.go cd ..

Download containerd

git clone https://github.com/macOScontainers/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/macoscontainers/macos-jail/ventura:latest

Aaaand... Run your first macOS container!

sudo go run cmd/ctr/main.go run --rm -t --runtime "$(pwd)/../rund/bin/containerd-shim-rund-v1" ghcr.io/macoscontainers/macos-jail/ventura:latest my_container /bin/sh -c 'echo "Hello from macOS container ^_^"'

If you want to build image from scratch, see https://github.com/macOScontainers/macos-jail[macos-jail] project.

=== Usage with BuildKit

Perform all the steps from <>.

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

[source,toml]

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

Then, from terminal:

[source,shell]

Download BuildKit

git clone https://github.com/macOScontainers/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/macoscontainers/macos-jail/ventura:latest RUN echo "Hello, World!" EOF

Aaaaad, build your first macOS image

sudo go run ./cmd/buildctl build --frontend=dockerfile.v0 --local context=. -local dockerfile=.

=== Usage with Docker

Perform all the steps from <>. You don't need BuildKit daemon to use Docker on macOS.

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

[source,json]

{ "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:

[source,shell]

Download Docker

git clone https://github.com/macOScontainers/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 macOS native container

sudo docker run --rm -it ghcr.io/macoscontainers/macos-jail/ventura:latest echo "Hello from macOS! ^_^"