macOS
New line, in development. A Mac joins a cluster as a mesh0 member and raft non-voter. See the current runtime contract for every runtime, including
apple.
SHC publishes macOS builds of shc, shcd and shc-x9s for darwin/amd64
(Intel) and darwin/arm64 (Apple Silicon). They ship as one .tar.gz per
architecture, alongside the Linux .deb / .rpm / .apk in the same release.
Status: what has actually been verified
Section titled “Status: what has actually been verified”Walked on a Mac. The v0.1.0 release, on an Apple Silicon Mac with macOS
27.0 and Apple’s container 1.5.0: the archive installed by the installer
and by hand, a root shc node join --runtime apple into a cluster a Linux
node leads, its two LaunchDaemons, a deployment, its logs, a drain and a
leave. An apple node is that walk, line
by line. At v0.1.0 a published port on the Mac answered a client on the
Mac’s own network only if the app read PROXY protocol. Since SHC-2660
pf redirects that client with its own address, walked on the Mac with a
host on its LAN.
Verified on every release. The artifacts. Every release cross-builds the
three binaries for both macOS architectures, and CI extracts the archive it
just built and asserts its contents: the binaries are 64-bit Mach-O of the
architecture the filename claims, the arm64 ones carry the code signature
Apple Silicon requires to execute anything at all, the raft engine rqlited
is present as a Mach-O of the same architecture, the five modules and the
bats helper are present and un-flattened, no Linux payload rode along, and
every file is owned root:root with a pinned mode
(scripts/darwin-payload-check.sh).
Not walked. The docker and podman runtimes on a Mac (Docker Desktop,
colima, Rancher Desktop, podman machine), the rootless path, a Mac as the
only node of its cluster, and Intel Macs. What this page says about them is
read off the source.
Nothing in the archive is a launchd job. A root shc init or
shc node join writes /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist
and /Library/LaunchDaemons/org.selfhostedcloud.shc-watchdog.plist and
bootstraps both into the system domain.
The subsystem-by-subsystem boundary, with the coded error each refusal raises and its own account of proven-versus-inferred, is Platform support.
Scope: what a Mac node is
Section titled “Scope: what a Mac node is”| Capability | macOS |
|---|---|
The apple runtime, Apple’s container CLI | walked: join, deployment, logs, drain, leave. Never the default: pass --runtime apple |
The docker or podman runtime | allowed, not walked. The cluster forms without the shc fabric |
| launchd jobs | written by a root shc init or shc node join: org.selfhostedcloud.shcd and org.selfhostedcloud.shc-watchdog |
Multi-node clusters, shc node join | mesh0 member and raft non-voter, with the raft engine the archive carries; walked |
| The shc fabric | apple: shc0 on a utun, walked. docker or podman: none, and --fabric shc refuses with X501391CLSPLT |
| Published ports | pf redirects a client on the Mac’s LAN or any other network, which keeps its address. The Mac itself, its containers and a VM behind one of its bridges reach the system Traefik and any app that reads PROXY protocol, and get a reset from the rest (SHC-2660) |
| Control-plane membership | out of scope. shc node update <node> --control-plane or shc node join --control-plane refuses with X501395ROLCAP |
| Apple container isolation from the node plane | built: the pf anchor com.apple/shc/node-plane |
A Mac has the mesh capability and never voter. It takes no
control-plane role, even at that fence’s home location. A host without
mesh refuses join with X501392CLJPLT. Mesh0 runs in shcd on a utun,
which cannot stay up through a daemon restart as a voter’s mesh must.
With the apple runtime a Mac carries the shc fabric on a utun, and
shc node info shows its fabric chunks like a Linux node’s. With docker or
podman it has no fabric: shc init says the cluster is formed without
the shc fabric, since the macOS fabric needs the apple runtime.
On an apple node shcd holds containers off the node’s control ports with the
pf child anchor com.apple/shc/node-plane, under com.apple/shc beside
vip, ports and policy, compiled from the same HostInput as the Linux
nft table inet shc_node_plane. SHC never edits /etc/pf.conf. A leave
empties the anchors. The design is in
Security, mesh networking.
Requirements
Section titled “Requirements”- For the
appleruntime: Apple Silicon, macOS 26 or newer and Apple’scontainerCLI. Walked on macOS 27.0 withcontainer1.5.0. An Intel Mac can run onlydockerorpodman. - For
dockerorpodman: a container runtime. Docker Desktop, colima, Rancher Desktop orpodman machine. Every one of them is a Linux VM; see What is different on a Mac. The docker runtime needsdocker composev2. restic,rsync,curl,socat,gitfor backups, deployment moves, log streaming and repo sync. The Linux packages declare these as hard dependencies; the archive cannot, so install them yourself. The daemon runs as root and keeps only directories root owns on its PATH, so on Apple Silicon, where Homebrew lives under/opt/homebrew, put restic where it looks:
brew install restic rsync socat gitsudo install -m 0755 "$(brew --prefix restic)/bin/restic" /usr/local/bin/resticInstall
Section titled “Install”With the installer
Section titled “With the installer”curl -fsSL https://downloads.selfhostedcloud.org/shc/install.sh | shThe installer reads only https://downloads.selfhostedcloud.org/shc/:
RELEASE names the newest release, and its archive and checksums sit under
<ver>/. SHC_INSTALL_BASE points it at a mirror of that tree instead.
On macOS the installer resolves the latest release’s
shc_<version>_darwin_<arch>.tar.gz, verifies its SHA-256 against the
release checksums, and extracts it over /usr/local with sudo. It does
not install a service; a root shc init or shc node join does that.
It ends with the root join that adds the Mac to a cluster with the apple
runtime.
Preview every step without touching the machine:
curl -fsSL https://downloads.selfhostedcloud.org/shc/install.sh | sh -s -- --dry-run--prefix takes /usr/local, the default, or /opt/homebrew. Those are the
two install roots SHC reads its apps from on a Mac (see
Where files land). The installer warns about any other
prefix, since SHC never finds the apps there, and writes it as you, without
sudo.
launchd runs <prefix>/bin/shcd as root. On Apple Silicon your login user
owns /opt/homebrew, and on an Intel Mac with Homebrew it owns
/usr/local/bin, so anything running as you can replace a shcd installed
there. The install still works, and the installer, shc init and
shc node join each warn with the directory and its owner. A stock
/usr/local is root’s.
By hand
Section titled “By hand”The archive is a prefix overlay (bin/, lib/, share/), so one
tar -C puts every file where the resolver already looks:
ver=0.1.0 # the release you want; the newest is in https://downloads.selfhostedcloud.org/shc/RELEASEarch=arm64 # or amd64 on Intelcurl -fsSLO "https://downloads.selfhostedcloud.org/shc/${ver}/shc_${ver}_darwin_${arch}.tar.gz"sudo tar -C /usr/local -xzf "shc_${ver}_darwin_${arch}.tar.gz"Both this and the installer work without credentials, from anywhere: the
mirror is public. They differ because they answer different questions: the
installer reads RELEASE for “what is the newest release?”, while a by-hand
install names a version, whose path never changes. Pin the versioned URL in
anything durable (a Dockerfile, a runbook, another installer). The digests are
beside it in shc_<ver>_checksums.txt.
Every file in the archive is owned root:root (0755 for the three binaries,
0644 for everything else), so extracting it as root produces the same result
the .deb produces on Linux.
Homebrew
Section titled “Homebrew”No. There will be no tap repository, and Homebrew refuses to install a
formula or a cask from outside a tap, so there is no brew channel to wire. The
archive above and scripts/install.sh are the macOS install. The ruling and
the refusal it rests on are written down in .goreleaser.yaml next to the
archive definition.
Where files land
Section titled “Where files land”With the default /usr/local prefix:
| Path | Contents |
|---|---|
/usr/local/bin/shc, shcd, shc-x9s | the binaries |
/usr/local/lib/shc/apps/ | the five modules (collector, keycloak, openobserve, postgres, traefik) |
/usr/local/lib/shc/tests/lib/common.sh | the shared bats helper the test runner sources |
/usr/local/lib/shc/exec-env/linux-arm64/exec-env | the exec helper the apple runtime shares into every container (a linux/arm64 binary: a container is a Linux VM) |
/usr/local/lib/shc/bin/rqlited | the raft engine shcd runs on a cluster member. Upstream rqlite publishes no macOS build, so the release builds it from the same pinned version the Linux packages carry. shcd finds it beside its own binary |
/usr/local/share/doc/shc/ | this page and the licence |
/usr/local/lib/shc is not an arbitrary choice: it is one of the install
roots core/paths probes when it resolves the install base, beside
/opt/homebrew/lib/shc, and every one of them contributes its apps/
directory to the shipped app roots (core/paths ShippedAppRoots). So
shc init places the modules from /usr/local/lib/shc/apps, shc install traefik finds the bundled app with no repo registration step, and the
implicit “shipped” catalog repo lists them in shc search.
State, config and cache follow the same rules as an unprivileged Linux
install (~/.local/share/shc, ~/.config/shc, ~/.cache/shc) as long as
you do not run as root. Run shc init or shc node join as root and they
move to the SAME FHS paths Linux uses: /etc/shc, /var/lib/shc,
/var/cache/shc, /var/log/shc. macOS has no /run, so the runtime
directory is /var/run/shc, the one deliberate divergence, and it names
the same place Linux reaches through its own /var/run → /run symlink.
A deployment’s data is kept beside the state home, not in it:
/var/lib/shc-volumes/<tenant>/<stack>/<environment>/mounts as root,
~/.local/share/shc-volumes rootless, SHC_VOLUMES_HOME to put it
elsewhere. An apple named volume that two services share, or that names
itself, is a directory there. shc init --force and shc node join --force
wipe the state home and leave this directory, as a forced leave says it
does, so an app installed again finds its data. shc uninstall removes a
deployment’s data from it.
A root init or join also adds these, outside the paths above:
| What | Where |
|---|---|
| the two LaunchDaemons | /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist, org.selfhostedcloud.shc-watchdog.plist; their logs are /var/log/shc/shcd.err.log and shc-watchdog.err.log |
a local group shc | with the user who ran the command as a member |
| a tmpfs for secrets | /var/run/shc-secrets |
| pf anchors | com.apple/shc and its children vip, ports, node-plane and policy; pf is enabled with a reference if it was off |
| IP forwarding | net.inet.ip.forwarding=1 while the Mac is a member |
| utun devices | mesh0 and, with the apple runtime, the fabric |
| Apple container networks | shc_fabric_<n> and one per deployment network, such as master_default_traefik_public |
A leave stops the deployment containers and keeps them, their images and
their networks, empties the pf anchors, and leaves the LaunchDaemons loaded,
so shcd keeps running with no cluster.
Those paths are not prefixed by $HOMEBREW_PREFIX. core/paths used
to do that and stopped, for two reasons that both failed silently: a
launchd job inherits no shell profile, so it resolved /usr/local while an
interactive CLI with brew shellenv loaded resolved /opt/homebrew: two
processes looking for each other’s socket in different places, and neither
prefix is inside any container runtime’s documented file-sharing set, which
is the wrong side of the bind-mount boundary for every named volume.
Running a node
Section titled “Running a node”The walked way is a root join with the apple runtime into a cluster a
Linux node leads. An apple node has every
line, from the archive to the leave; its core is:
sudo container system startssh root@home01 shc node token --fields token -o text | sudo shc node join - --name mac01 --runtime appleThe join writes and starts both LaunchDaemons. It enrolls the Mac at the
address of the interface its default route leaves by; if the Mac reaches the
cluster another way, name that interface with --nic, or the enrollment is
refused 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.
Rootless, with docker or podman
Section titled “Rootless, with docker or podman”Not walked. Apple’s container apiserver refuses users other than root, and
mesh0, the fabric and pf need root too, so a rootless node runs only
docker or podman, on one Mac. Two exports, then the daemon, then init:
export SHC_STATE_HOME="$HOME/.local/share/shc"export SHC_RUNTIME_DIR="/tmp/shc-$(id -u)"shcd &shc initBoth exports name the value SHC would compute for you anyway. Setting them explicitly switches off two Linux-shaped behaviours:
SHC_STATE_HOMEmarks the run as sandboxed, soshc initstays rootless instead of re-executing itself undersudo, and leaves launchd alone: it printsstate-home override detected; skipping service activation (enable/start the daemon yourself). That matters on a Mac in a way it does not on Linux:dockeris a per-user VM, andsudo’senv_resetdropsDOCKER_HOSTandDOCKER_CONTEXT, so an elevatedshc initis blind to the runtime it is supposed to drive. Staying in$HOMEalso keeps state on the one host path Docker Desktop, colima, Rancher Desktop andpodman machineall share into their VM by default.SHC_RUNTIME_DIRtells the CLI where an unprivileged daemon’s socket lives. Without it the CLI probes only the system socket paths until the node has an identity on disk, and a freshly started daemon looks absent.
A variable for the supervised daemon
Section titled “A variable for the supervised daemon”launchd has no drop-in directory, so a variable for the LaunchDaemon’s shcd
goes in the job itself, under EnvironmentVariables:
sudo plutil -replace EnvironmentVariables.SHC_RQLITED_BIN -string /usr/local/lib/shc/bin/rqlited /Library/LaunchDaemons/org.selfhostedcloud.shcd.plistsudo launchctl bootout system/org.selfhostedcloud.shcdsudo launchctl bootstrap system /Library/LaunchDaemons/org.selfhostedcloud.shcd.plistGive the bootout a few seconds to finish before the bootstrap: straight after
it, launchd refuses with Bootstrap failed: 5: Input/output error and the
daemon stays unloaded until you run the bootstrap again.
shc init and shc node join write that file again and keep every entry you
added. PATH and SHC_MODE are SHC’s own and are rendered fresh each time,
and nothing outside EnvironmentVariables is kept. Entries are kept only from
a file that is root’s alone: owned by root, not writable by group or other, in
directories that are the same. From any other file the command warns and writes
the job without them. The watchdog job, org.selfhostedcloud.shc-watchdog,
keeps none.
What is different on a Mac
Section titled “What is different on a Mac”Differences that do not announce themselves at run time. Some were observed on the walk above; the rest are read off the source, or are properties of the macOS and container-runtime ecosystem that SHC has inherited from documentation and not observed, flagged as such.
The ones that matter most are not refusals. A refusal is loud and names its own cause; these are surfaces that return a PLAUSIBLE ANSWER about the wrong machine, or a zero where the honest answer is “unknown”.
Docker is a Linux VM. With the docker runtime, bind mounts resolve
inside that VM, not on your Mac. Docker Desktop shares /Users, /Volumes,
/private and /tmp by default; colima and Lima share your home directory.
A deployment whose state lives outside a shared path is reported to fail in
two different ways: Docker Desktop refuses the mount outright, while colima
and Lima silently create an empty directory inside the VM, so the
container starts, reports healthy, and reads nothing. Inherited,
unobserved: the silent-empty-directory behaviour in particular is the
dangerous half of this claim and nobody here has watched it happen. Keeping
SHC_STATE_HOME under $HOME is believed to avoid the whole class, and is
cheap either way.
Host metrics measure the VM, and now they say so. The collector’s
hostmetrics receiver runs inside the container runtime’s VM, so the CPU,
memory and disk figures it reports are the VM’s, faithfully labelled as the
host’s. They are not your Mac’s, and nothing downstream could tell: VM
metrics and host metrics carry the same names and the same units, so the
dashboard renders and every number is internally consistent about the wrong
machine.
The render therefore stamps the answer onto the data. Every series from the node-metrics pipeline carries:
| Resource attribute | On macOS | On Linux |
|---|---|---|
shc.host_metrics.subject | container-runtime-vm | node |
shc.node.os | darwin | linux |
Group or filter on shc.host_metrics.subject before comparing a Mac’s node
metrics with a Linux node’s: they measure different machines. The daemon
also logs X503122COLVMS once per transition when it deploys such a
collector, so the fact reaches the log as well as the data. Container
metrics are unaffected and carry no stamp: a container’s own CPU is its own
on every platform. (It is still expressed relative to the VM’s CPUs, so “50%
of CPU” means 50% of what the VM was given.) Still: do not size your Mac from
the node figures.
One node fact macOS cannot answer, and a zero is not it. shcd runs
natively, so the node health snapshot describes your Mac. node.health
carries an unmeasured_facts list, and the utilization gauge for an
unmeasured fact is omitted rather than published as a flat 0%.
| Fact | On macOS |
|---|---|
| CPU cores, disk total / used / percent | Measured. |
| Memory total | hw.memsize. |
| Memory used / percent | Measured, from the free, purgeable, speculative and file-backed page counts. |
| Load average | vm.loadavg. |
| CPU percent | Not measured: named as cpu.percent. |
A node whose memory read fails reports degraded rather than healthy. Linux measures CPU percent with an interval sampler; macOS has no such sampler yet.
The trust bundle has public roots on a Mac. SHC builds a node trust
bundle from the host’s public CA roots plus its own anchors and points apps’
SSL_CERT_FILE at it. SSL_CERT_FILE REPLACES a container’s root set
rather than adding to it, so a missing host half would leave the container
trusting the SHC root and nothing else. macOS ships a PEM bundle at
/etc/ssl/cert.pem, the last of the five paths SHC reads (observed: 128
roots on macOS 27.0), so the bundle carries public roots. Were none of the
five there, X500703CATRSTS would name them all.
The node picks its own address. Container runtimes and VMs add
interfaces to your Mac, such as bridge100 at 192.168.64.1, which are
private and sort early. The default route resolves without /proc, and the
tie-break deprioritizes container-runtime and overlay interfaces: observed,
the join chose the Wi-Fi interface its default route leaves by over a VM
bridge and Apple’s container bridges. Pass --nic to choose another; the
leader refuses an enrollment whose address is not the one the Mac’s
connection comes from (X403092ENRSIP).
HOMEBREW_PREFIX moves where the BINARIES go, and nothing else. It is
your install prefix. It does not move the system paths any more; see
Where files land. core/paths derived /etc, /var
and /run from it until that was removed: a launchd job inherits no shell
profile and resolved /usr/local while an interactive CLI resolved
/opt/homebrew, so the daemon and the CLI looked for each other’s socket in
different directories and the CLI silently fell through to
http://localhost:8000. The installer no longer warns about it (SHC-2661).
Downloaded binaries are not quarantined by curl. Observed: the archive
curl fetched carries com.apple.provenance but no com.apple.quarantine,
and the extracted binaries run. A browser download does set the quarantine
attribute, and Gatekeeper then refuses the binary as coming from an
unidentified developer; clear it with
xattr -dr com.apple.quarantine /usr/local/bin/shc*. There is no Apple
Developer ID signature or notarisation on these builds; that needs a paid
Apple Developer account and a Developer ID certificate, and it is not done.
The arm64 binaries do carry the ad-hoc signature Go’s linker writes, which is
verified on every release artifact and is what Apple Silicon requires to
execute them at all.
Removing
Section titled “Removing”sudo rm -f /usr/local/bin/shc /usr/local/bin/shcd /usr/local/bin/shc-x9ssudo rm -rf /usr/local/lib/shc /usr/local/share/doc/shcrm -rf ~/.local/share/shc ~/.local/share/shc-volumes ~/.config/shc ~/.cache/shc # rootless state, data, config, cacheIf you ran shc init or shc node join as root, the daemon and its state are
not under $HOME. Leave the cluster first, then take out what the join
added:
sudo shc node leavesudo launchctl bootout system/org.selfhostedcloud.shcdsudo launchctl bootout system/org.selfhostedcloud.shc-watchdogsudo rm -f /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist /Library/LaunchDaemons/org.selfhostedcloud.shc-watchdog.plistsudo umount /var/run/shc-secretssudo rm -rf /etc/shc /var/lib/shc /var/lib/shc-volumes /var/cache/shc /var/log/shc /var/run/shc /var/run/shc-secretssudo dseditgroup -o delete shcsudo container list --allsudo container network listThe last two list what the leave kept: the stopped containers of SHC’s
deployments and their networks. Remove those with sudo container rm and
sudo container network rm.
/var/lib/shc holds the database, the vault and every deployment, and
/var/lib/shc-volumes the deployments’ data. Removing them is not
reversible.
Next steps
Section titled “Next steps”- An apple node: the walked join, deployment and leave
- Platform support: the host-OS boundary: exactly what refuses off Linux and with which code
- Installation: the Linux node install
- Quick start: deploy your first app
- Core concepts: tenant, environment, stack, deployment