Skip to content
SHC Docs

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.

home01
$ shc version
shc version 0.1.0
build: embedded-tui
mac01
$ 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 version
shc version 0.1.0
build: embedded-tui
$ brew install restic rsync socat git
...
$ sudo install -m 0755 /opt/homebrew/bin/restic /usr/local/bin/restic

The 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.

mac01
$ sudo container system start
Launching container-apiserver...
Testing access to container-apiserver...
Verifying machine API server is running...
$ sudo container system status
FIELD VALUE
status 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.

mac01
$ 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.shcd
system/org.selfhostedcloud.shcd = {
active count = 1
path = /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist
type = LaunchDaemon
state = running
...
home01
$ shc node ls --verbose
NAME ID HOST INTERNAL UNDERLAY RUNTIME CORES MEMORY FREE CORES FREE MEMORY STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTER
home01 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 yes
mac01 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 no

mac01 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.

home01
$ shc node info mac01
ID HOSTNAME RUNTIME AVAILABILITY INTERNAL ADDRESS UNDERLAY ADDRESS CLOUD LOCATION IS VOTER FABRIC GRANT FABRIC TENANT SLOTS FABRIC FULLEST BRIDGE
node-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 mac01
NAME STATUS HEALTH STATUS CHECKED AT
mac01 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.

home01
$ shc install ~/learn/nginx -s macweb --runtime apple --expose 18084=nginx:80
installing deployment "macweb"
[macweb] Healthy 1/1
✔ nginx healthy
✔ installed deployment "macweb"
exposure: lan
$ shc ls
STACK TENANT ENV APP STATUS NODES
keycloak master default keycloak running home01
openobserve master default openobserve running home01
postgres master default postgres running home01
traefik master default traefik running home01, mac01
macweb prod prod /root/learn/nginx running mac01
web prod prod /root/learn/nginx running home01

On 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.

mac01
$ sudo container list --all
ID 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.

home01
$ curl -s http://192.168.1.20:18084/
<!doctype html>
<title>hello</title>
<p>Hello from SHC.</p>
home01
$ 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.

home01
$ shc uninstall macweb -y
uninstalling 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"
home01
$ 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.

mac01
$ 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
home01
$ shc node ls
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTER
home01 healthy ready active learn learn/home ok 0.1.0 yes yes
...

Next: A Hetzner node.