Skip to content
SHC Docs

Platform support

New line, in development. Membership depends on host capabilities. See the current runtime contract.

Cluster membership and roles depend on the host capabilities recorded by ce/core/hostplat. Linux provides the mesh, fabric and voter capabilities. macOS provides mesh through the daemon’s userspace WireGuard device on a utun.

The rule the codebase follows, everywhere:

A mutating operation outside the supported scope refuses with a coded error naming the missing kernel facility. A read/status operation answers truthfully that the thing is absent.

A refusal is never a silent no-op.


Status of this page: the refusals are tested, macOS is not verified

Section titled “Status of this page: the refusals are tested, macOS is not verified”

Read the matrix below as a scope statement, not a passed acceptance test. Nothing described here has been run on a Mac.

What is tested: every refusal and every deliberate non-refusal, driven from Linux through the hostplat seam (Override("darwin")), plus a paired assertion per guard that the Linux path is unchanged. That covers the guard logic and its wiring, which is what this boundary is.

What is not tested, and is inference rather than observation:

  • that /etc/fstab is present and writable on macOS in the shape the NFS teardown assumes; this claim is the sole justification for the disable asymmetry below, and stock macOS does not ship an /etc/fstab;
  • that launchctl bootstrap / dseditgroup behave as the launchd arm assumes, and that a missing systemctl surfaces as exec: "systemctl": executable file not found.

The refusals do not depend on any of these being right (they fire before that code is reached), but the explanations in their messages do. Correct them if a Mac ever says otherwise.

Service supervision on macOS is wired: host activation dispatches through a platform seam, and its launchd arm writes the LaunchDaemon org.selfhostedcloud.shcd to /Library/LaunchDaemons and bootstraps it into the system domain. Nothing packages that plist, so activation is what creates it. Like everything else here, that path is exercised against a fake command runner on Linux, not against launchd.


HostScopeNotes
Linux (amd64, arm64)Everything. Single node and multi-node, every runtime, the shc fabric, shared storage.The only platform with published shc / shcd / shc-x9s artifacts. Verified.
macOS (arm64, amd64)Single node, or a mesh0 member of a cluster. The shc fabric on the apple runtime only.Joins as a raft non-voter with a mesh0 address. On the apple runtime it holds shc0 chunks once its pf policy loads. Build from source.
Windows / otherNo cluster membership.Join refuses with X501392CLJPLT because no mesh0 device is available.

An empty --runtime detects a live docker socket as docker and a live podman socket as podman, and otherwise records docker (modules/cluster/local_init.go detectRuntimeFrom). An empty --fabric records shc where that runtime can attach the fabric: on Linux, and on a Mac running apple. Elsewhere init forms the cluster without the shc fabric and warns. --fabric none is refused where the runtime can attach it (X400389FABOFF).

--runtime podman is a runtime executor.New answers. RunsOn does not bind it to Linux. Init warns that a podman cluster is single-node only (modules/cluster/service.go CheckInit).


Hostmeshfabricvoter
LinuxYesYesYes
macOSYesNoNo
Windows / otherNoNoNo

mesh needs a WireGuard device for mesh0: kernel WireGuard over netlink, or the daemon’s userspace device on a utun. fabric needs kernel WireGuard over netlink and nftables for shc0. voter needs a mesh0 device that stays up while the daemon restarts. A utun owned by shcd cannot provide that.

A Mac join receives a mesh0 address and a non-voter raft seat. It receives no shc0 subnet or fabric address, and its container engine is not checked for fabric support. It takes no derived control-plane membership, even at the control plane’s home location. A join with --control-plane on a host without voter refuses with X501395ROLCAP, naming the missing capability. A row with no capabilities has none.

Built (SHC-1481). An apple node holds its containers off the node plane with the pf child anchor com.apple/shc/node-plane, compiled from the same HostInput as the Linux nft table inet shc_node_plane, and loaded by shcd while the Mac is a member. The design is in Security, mesh networking.

The guards run before the requested role is granted. Joiners check their own capabilities before sending the single-use token; leaders check the declared list before writing a node row.

Swarm is not a runtime and not a host facility. shc init --runtime swarm and a join runtime of swarm are refused (X400422CLSRUN). --fabric swarm is refused (X400371FABSWM). SHC does not run docker swarm init. See New-line runtime.

SubsystemRefused operationsCodeMissing facility
Cluster fabricshc init --fabric shc without fabricX501391CLSPLTKernel WireGuard over netlink and nftables
Cluster joinshc node join without meshX501392CLJPLTA WireGuard device for mesh0, either kernel WireGuard over netlink or a userspace device on a utun
Node roleEnrol without mesh, or control-plane membership without voterX501395ROLCAPThe facility named by the missing capability
WireGuard fabric deviceApplier.Apply on a non-Linux buildX500354FABDEVKernel WireGuard over netlink
Node-local NFSenable-server, enable-client, disableX501393NFSPLTnfs-kernel-server, exportfs, /etc/exports.d, /etc/nfs.conf.d, and a systemd unit to run them
Cephcephfs enable, add osdX501394CEPPLTcephadm places mon/mgr/osd/mds as systemd units; clients mount via the kernel rbd/cephfs drivers

The 39x sequence is reserved across modules for host-OS scope refusals. Every message in the block names the facility, never a bare “unsupported”: an operator who reads “kernel WireGuard over netlink” knows it is not coming, one who reads “unsupported on darwin” files a feature request.

What deliberately does not refuse off Linux

Section titled “What deliberately does not refuse off Linux”

These are as important as the refusals. Getting them wrong turns a laptop into a wall of errors, which teaches operators to ignore the error that matters on a node.

SurfaceBehaviour off Linux
Fabric device status (shc cluster fabric status)Reports shc0 absent. That is the true and complete answer.
Cluster mesh (mesh0) on darwinRuns in this process on a utun (userspace WireGuard, SHC-1287). Linux keeps kernel WireGuard over netlink. A host that is neither has no mesh0 applier; its Apply is the fabric-device refusal already listed above.
NFS node statusReports is_server=false, is_installed=false, mount_active=false.
Cluster mesh status / diagnoseAnswers normally; peer state is still reported honestly.
Cluster mesh disableStays reachable. It is the way out of a half-applied mesh.
Single-node docker initNot refused. An empty runtime detects docker or podman and otherwise records docker. An empty fabric records shc only where that runtime attaches it.

Note the asymmetry between cluster mesh disable and the NFS disable, which is refused: NFS teardown rewrites /etc/fstab, a host file that does not belong to SHC. Nothing off Linux could ever have been enabled, so refusing it denies the operator nothing, which is why the asymmetry is cheap even though the premise behind it (that macOS presents an /etc/fstab worth protecting) is unverified, and stock macOS ships none.


Three things are true on macOS regardless of what SHC does, and all three are stated here rather than hidden:

  1. Docker on macOS is a Linux VM (Docker Desktop, colima, Rancher Desktop, podman machine). Anything a container observes about “the host” is really the VM. The metrics collector’s hostmetrics receiver runs inside that VM and faithfully reports the VM’s CPU, memory and disk as if they were the Mac’s, which is undetectable downstream, because VM metrics and host metrics carry the same names and the same units. So the render STAMPS the answer onto the data: every node-metrics series carries shc.host_metrics.subject (node | container-runtime-vm) and shc.node.os, and the daemon logs X503122COLVMS on transition. Container metrics are deliberately not stamped: a container’s own CPU is its own on every platform. Details, plus the node facts macOS cannot measure at all, are in macOS.
  2. The macOS artifact is an archive, not a package. Every release publishes shc_<ver>_darwin_<arch>.tar.gz for amd64 and arm64, a prefix overlay for /usr/local; see macOS.
  3. The daemon runs under launchd, and activation is what installs it. No archive ships a plist, so /Library/LaunchDaemons/org.selfhostedcloud.shcd.plist and its watchdog’s exist only after a root shc init or shc node join. An unprivileged run cannot start the daemon and says so.

  • ce core/hostplat: the host-OS seam (GOOS(), IsLinux(), Override() for tests) and the package doc that states this scope boundary once, authoritatively.
  • ce modules/fabric/applier_other.go: the original pattern: a //go:build !linux stub whose Apply refuses with a code and whose Status truthfully reports absence.

Build tags are used only where the link would otherwise break. Everything else is a runtime check, because logic that compiles on one GOOS can only be tested on that GOOS, and the refusals need tests that prove both halves: that they fire off Linux and that Linux is untouched.