An apple node
This page needs a Mac: Apple Silicon, macOS 26 or newer, with Apple’s
container command installed. The other pages of this ladder do not need
it; skip to the clouds if you have no Mac.
An apple node runs each service as its own Linux micro-VM through Apple’s
container CLI. There is no compose on a Mac: SHC translates the
deployment itself. A Mac joins the mesh, holds no vote and never joins the
control plane; shc node join --control-plane on it refuses with
X501395ROLCAP. The apple runtime runs only on macOS, and a Linux node
that names it refuses with X400789EXEHST.
Install SHC on the Mac from the release archive, which is a prefix overlay
for /usr/local. A node runs the version its cluster runs: read it on
home01, then take the darwin archive of that version, with VERSION
below replaced by what it printed.
$ shc versionshc version 0.1.0build: embedded-tui$ curl -fsSLO https://downloads.selfhostedcloud.org/shc/VERSION/shc_VERSION_darwin_arm64.tar.gz$ sudo tar -C /usr/local -xzf shc_VERSION_darwin_arm64.tar.gz$ shc versionshc version 0.1.0build: embedded-tui$ brew install restic rsync socat git...$ sudo install -m 0755 /opt/homebrew/bin/restic /usr/local/bin/resticThe daemon runs as root with only root-owned directories on its path, so restic is copied where it looks. Start Apple’s container system as root, so the apiserver lives in the system domain the daemon reaches.
$ sudo container system startLaunching container-apiserver...Testing access to container-apiserver...Verifying machine API server is running...$ sudo container system statusFIELD VALUEstatus running...Join the Mac. A root shc node join writes the LaunchDaemons
org.selfhostedcloud.shcd and org.selfhostedcloud.shc-watchdog and
starts them; mac01 is a location of its own, since the Mac is on your
desk and not in home.
The join asks home01 for its token over ssh, as root, so your Mac must
reach home01 by name with a key root there accepts. It enrolls the Mac at
the address of the interface its default route leaves by. If the Mac
reaches home01 another way, such as a VM on the Mac or a VPN, add --nic
with that interface, or home01 refuses the enrollment with
X403092ENRSIP. A Mac whose network lies inside the cluster’s service VIP
range is refused with X409450ADROVL, which names the --address-block
to make the cluster with instead.
$ ssh root@home01 shc node token --fields token -o text | sudo shc node join - --name mac01 --cloud learn --location desk --runtime apple✔ joined cluster as node "mac01" at 192.168.1.20$ sudo launchctl print system/org.selfhostedcloud.shcdsystem/org.selfhostedcloud.shcd = { active count = 1 path = /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist type = LaunchDaemon state = running...$ shc node ls --verboseNAME ID HOST INTERNAL UNDERLAY RUNTIME CORES MEMORY FREE CORES FREE MEMORY STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTERhome01 node-7ae98446e8e6 home01 10.96.0.1:4003 192.168.1.10 docker 4 7.7G 4.0 7.7G healthy ready active learn learn/home ok 0.1.0 yes yesmac01 node-0df0c511186b mac01 10.96.0.2:4003 192.168.1.20 apple 32 512.0G 32.0 512.0G healthy ready active learn learn/desk ok 0.1.0 no nomac01 reads apple, with no under both LEADER and VOTER. It holds
fabric chunks like a Linux node: the apple runtime carries the shc fabric
on a utun, each replica on a vmnet network of its own.
$ shc node info mac01ID HOSTNAME RUNTIME AVAILABILITY INTERNAL ADDRESS UNDERLAY ADDRESS CLOUD LOCATION IS VOTER FABRIC GRANT FABRIC TENANT SLOTS FABRIC FULLEST BRIDGEnode-0df0c511186b mac01 apple active 10.96.0.2:4003 192.168.1.20 learn learn/desk false 10.64.32.0/20 1 of 31 master, 3 of 125 addresses$ shc node health mac01NAME STATUS HEALTH STATUS CHECKED ATmac01 active healthy 2026-10-10T18:53:52Z...Install the nginx directory for the apple runtime. The Mac is the only apple node, so the deployment lands there.
$ shc install ~/learn/nginx -s macweb --runtime apple --expose 18084=nginx:80installing deployment "macweb"[macweb] Healthy 1/1✔ nginx healthy✔ installed deployment "macweb"exposure: lan$ shc lsSTACK TENANT ENV APP STATUS NODESkeycloak master default keycloak running home01openobserve master default openobserve running home01postgres master default postgres running home01traefik master default traefik running home01, mac01macweb prod prod /root/learn/nginx running mac01web prod prod /root/learn/nginx running home01On the Mac the service is a container the container CLI lists, beside
the system ingress’s own. Its logs are the file Apple’s apiserver writes
for it, which SHC reads through its log index like any other node’s.
$ sudo container list --allID IMAGE OS ARCH STATE IP CPUS MEMORY STARTED...prod_prod_macweb-nginx-r0 docker.io/library/nginx:1.27-alpine linux arm64 running 10.64.33.2/25,10.32.1.2/24 4 1024 MB 2026-10-10T18:53:58Z...On macOS a published port answers a local caller only through the
system ingress, so curl on the Mac itself prints nothing. Read the page
from another node, at the address the join printed. A home01 that is a VM
on the Mac behind the Mac’s own NAT counts as the Mac too and gets a
reset, so read the page from a machine elsewhere on the Mac’s network.
$ curl -s http://192.168.1.20:18084/<!doctype html><title>hello</title><p>Hello from SHC.</p>$ shc logs nginx -s macweb --tail 5...nginx-r0 | 2026/10/10 18:53:59 [notice] 9#9: start worker process 37...Uninstall macweb and take the Mac out of the cluster, so the cloud pages
start from the same three Linux nodes whether or not you had a Mac. The
system ingress keeps a traefik replica on every node, mac01 included, so
a Mac that still hosts one refuses to leave with X409025LVDEPS: drain
it from a Linux node first and the cluster moves what it hosts.
$ shc uninstall macweb -yuninstalling deployment "macweb"[macweb] Complete 6/6✔ remove from mac01✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ stop the replicas on mac01✔ remove the copy on home01✔ uninstalled deployment "macweb"$ shc node drain mac01 --yes...✔ drained node "mac01"The leave keeps the Mac’s images and stops its containers. The two
LaunchDaemons stay loaded, so shcd keeps running with no cluster.
$ sudo shc node leave✔ node "mac01" left the cluster✔ membership state moved to /var/lib/shc/left-cluster-20261010T185740Z-b7ee28f7-a5c8-4e46-b97f-4c3225d476c7✔ member subsystems and deployment containers stopped; images, deployment files and deployment volumes kept$ shc node lsNAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTERhome01 healthy ready active learn learn/home ok 0.1.0 yes yes...Next: A Hetzner node.