Skip to content
SHC Docs

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.


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.


CapabilitymacOS
The apple runtime, Apple’s container CLIwalked: join, deployment, logs, drain, leave. Never the default: pass --runtime apple
The docker or podman runtimeallowed, not walked. The cluster forms without the shc fabric
launchd jobswritten by a root shc init or shc node join: org.selfhostedcloud.shcd and org.selfhostedcloud.shc-watchdog
Multi-node clusters, shc node joinmesh0 member and raft non-voter, with the raft engine the archive carries; walked
The shc fabricapple: shc0 on a utun, walked. docker or podman: none, and --fabric shc refuses with X501391CLSPLT
Published portspf 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 membershipout of scope. shc node update <node> --control-plane or shc node join --control-plane refuses with X501395ROLCAP
Apple container isolation from the node planebuilt: 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.


  • For the apple runtime: Apple Silicon, macOS 26 or newer and Apple’s container CLI. Walked on macOS 27.0 with container 1.5.0. An Intel Mac can run only docker or podman.
  • For docker or podman: a container runtime. Docker Desktop, colima, Rancher Desktop or podman machine. Every one of them is a Linux VM; see What is different on a Mac. The docker runtime needs docker compose v2.
  • restic, rsync, curl, socat, git for 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:
Terminal window
brew install restic rsync socat git
sudo install -m 0755 "$(brew --prefix restic)/bin/restic" /usr/local/bin/restic

Terminal window
curl -fsSL https://downloads.selfhostedcloud.org/shc/install.sh | sh

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

Terminal window
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.

The archive is a prefix overlay (bin/, lib/, share/), so one tar -C puts every file where the resolver already looks:

Terminal window
ver=0.1.0 # the release you want; the newest is in https://downloads.selfhostedcloud.org/shc/RELEASE
arch=arm64 # or amd64 on Intel
curl -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.

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.


With the default /usr/local prefix:

PathContents
/usr/local/bin/shc, shcd, shc-x9sthe binaries
/usr/local/lib/shc/apps/the five modules (collector, keycloak, openobserve, postgres, traefik)
/usr/local/lib/shc/tests/lib/common.shthe shared bats helper the test runner sources
/usr/local/lib/shc/exec-env/linux-arm64/exec-envthe exec helper the apple runtime shares into every container (a linux/arm64 binary: a container is a Linux VM)
/usr/local/lib/shc/bin/rqlitedthe 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:

WhatWhere
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 shcwith the user who ran the command as a member
a tmpfs for secrets/var/run/shc-secrets
pf anchorscom.apple/shc and its children vip, ports, node-plane and policy; pf is enabled with a reference if it was off
IP forwardingnet.inet.ip.forwarding=1 while the Mac is a member
utun devicesmesh0 and, with the apple runtime, the fabric
Apple container networksshc_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.


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:

Terminal window
sudo container system start
ssh root@home01 shc node token --fields token -o text | sudo shc node join - --name mac01 --runtime apple

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

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:

Terminal window
export SHC_STATE_HOME="$HOME/.local/share/shc"
export SHC_RUNTIME_DIR="/tmp/shc-$(id -u)"
shcd &
shc init

Both exports name the value SHC would compute for you anyway. Setting them explicitly switches off two Linux-shaped behaviours:

  • SHC_STATE_HOME marks the run as sandboxed, so shc init stays rootless instead of re-executing itself under sudo, and leaves launchd alone: it prints state-home override detected; skipping service activation (enable/start the daemon yourself). That matters on a Mac in a way it does not on Linux: docker is a per-user VM, and sudo’s env_reset drops DOCKER_HOST and DOCKER_CONTEXT, so an elevated shc init is blind to the runtime it is supposed to drive. Staying in $HOME also keeps state on the one host path Docker Desktop, colima, Rancher Desktop and podman machine all share into their VM by default.
  • SHC_RUNTIME_DIR tells 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.

launchd has no drop-in directory, so a variable for the LaunchDaemon’s shcd goes in the job itself, under EnvironmentVariables:

Terminal window
sudo plutil -replace EnvironmentVariables.SHC_RQLITED_BIN -string /usr/local/lib/shc/bin/rqlited /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist
sudo launchctl bootout system/org.selfhostedcloud.shcd
sudo launchctl bootstrap system /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist

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


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 attributeOn macOSOn Linux
shc.host_metrics.subjectcontainer-runtime-vmnode
shc.node.osdarwinlinux

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

FactOn macOS
CPU cores, disk total / used / percentMeasured.
Memory totalhw.memsize.
Memory used / percentMeasured, from the free, purgeable, speculative and file-backed page counts.
Load averagevm.loadavg.
CPU percentNot 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.


Terminal window
sudo rm -f /usr/local/bin/shc /usr/local/bin/shcd /usr/local/bin/shc-x9s
sudo rm -rf /usr/local/lib/shc /usr/local/share/doc/shc
rm -rf ~/.local/share/shc ~/.local/share/shc-volumes ~/.config/shc ~/.cache/shc # rootless state, data, config, cache

If 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:

Terminal window
sudo shc node leave
sudo launchctl bootout system/org.selfhostedcloud.shcd
sudo launchctl bootout system/org.selfhostedcloud.shc-watchdog
sudo rm -f /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist /Library/LaunchDaemons/org.selfhostedcloud.shc-watchdog.plist
sudo umount /var/run/shc-secrets
sudo rm -rf /etc/shc /var/lib/shc /var/lib/shc-volumes /var/cache/shc /var/log/shc /var/run/shc /var/run/shc-secrets
sudo dseditgroup -o delete shc
sudo container list --all
sudo container network list

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