Hybrid Sidecar Architecture (0x7F-MACSYNTH)

The Mac Mini is an Apple Silicon machine with opinions about who gets to touch its Neural Engine. The OpenClaw core is a Linux-first application that would prefer you forgot macOS exists. The Hybrid Sidecar Architecture is the peace treaty between them — a dual-plane system where the host keeps hardware control and a guest VM handles application logic, talking over loopback TCP like two neighbors who share a wall and very specific rules about noise.

This architecture was formalized in Council Decree 0x7F-MACSYNTH. What follows is the operational reality of that decree.

Note

This replaces any prior assumption that OpenClaw runs in a Docker container. It does not — it runs in a Lima VM. The Mac Mini’s ARM64 topology and macOS kernel constraints make a single fused machine roughly as practical as teaching a cat to fetch: theoretically possible, universally inadvisable.

The Dual-Plane Design

Two planes, a strict division of labor.

The Host Plane (macOS Native) is the Hardware Abstraction Layer. It drives the Apple Neural Engine via MLX, owns the macOS networking stack (firewall, DNS), runs the user-facing interfaces, and hosts the Sanctum Proxy. Everything that needs Metal or native macOS TTY registration lives here — including signal-cli, which containerization breaks outright.

The Container Plane (Lima VM + OrbStack) is the Logic Execution Engine. The OpenClaw core runs inside a Lima VM (sanctum-vm, Apple vz hypervisor, aarch64, 4 CPU / 8 GiB), reached from the host on 127.0.0.1:1977. OrbStack is also present, but it runs only the ancillary containers — Home Assistant, Outline and its Postgres/Redis/MinIO — not OpenClaw. The VM is a sidecar: it doesn’t replace the host, it augments it. (Colima ran the ancillaries through 2026-04-27; OrbStack replaced it, and the leftover Colima LaunchAgent was retired 2026-05-16. See The Vajrayogini Cut.)

The two planes talk over loopback TCP: limactl hostagent forwards the guest’s :1977 to the host’s 127.0.0.1:1977 over the bridge100 vmnet interface. The guest never touches a physical interface or hardware accelerator directly — it asks politely, over loopback, and the host decides whether to comply.

Component Placement

The Council decreed strict segregation of duties. Here’s where everything lives.

Component	Plane	Port	Interface	Notes
signal-cli	Host	8080 (HTTP), 7583 (TCP)	127.0.0.1	Native — containerization breaks TTY registration and device pairing
Coder MLX (sanctum-mlx-codestral)	Host	3301	127.0.0.1	Codestral-22B-v0.1-4bit, the CODER role; rust+mlx-rs, plain HTTP on loopback. Replaced the retired socat/LM-Studio coder bridge on 2026-06-07.
Sanctum Proxy (proxyd)	Host	4040	*	Rust LLM-routing daemon — fans requests across OpenRouter / Gemini / local providers (smart_route). See Sanctum Proxy.
MLX Runtime (sanctum-mlx)	Host	1337 (mTLS)	127.0.0.1 + Tailscale	High-performance inference path via Metal; TLS cert + key per the com.sanctum.mlx plist. See Dynamic Model Routing.
OpenClaw Core	VM	1977	127.0.0.1 (forwarded)	Runs inside sanctum-vm; surfaced to host loopback by limactl hostagent. /health returns {"ok":true,"status":"live"}.
Sanctum Bridge	Host	8443	127.0.0.1	Python sanctum_bridge — the Apple-side bridge (iMessage / Calendar / Contacts), loopback only.
OrbStack (Docker)	Host	—	—	Native macOS container runtime for the ancillary services (Home Assistant, Outline) — not OpenClaw.

Caution

Port 1977 is the guest’s, not the host’s — forwarded to 127.0.0.1 only, never to the LAN. If you find it answering on a non-loopback address, someone changed the Lima portForwards block. They shouldn’t have. Stop them.

How the Host Reaches the Guest

There is no bespoke broker daemon between the planes — no TLV bytes to decode, no socket protocol to memorize. The boundary is Lima’s own port-forwarder; the contract is plain TCP.

1. Forward: limactl hostagent (the process that actually holds :1977 on the host) tunnels each configured guest port to a host loopback address over bridge100 — the same SSH-backed forwarding Lima gives every guest, no custom code.
2. Route: When OpenClaw needs inference it calls the host’s MLX over loopback — :1337 (mTLS) for the general path, :3301 for the coder; for Signal, signal-cli on :8080. Plain HTTP/JSON, and the host answers. External LLM traffic skips OpenClaw entirely and routes through the Sanctum Proxy on :4040 — a model router, not a reverse proxy into the VM.

Tip

The VM is a clean blast boundary. A compromised OpenClaw core is trapped in a Linux guest that can reach the host only through the loopback ports Lima chose to forward — paranoia that feels excessive until the one time it isn’t.

Startup Sequence

The host doesn’t wait for you to press buttons — the stack is dependency-locked under launchd. For the full plist reference, see LaunchAgents & LaunchDaemons.

Phase 1: VM and Engine Boot

com.sanctum.vmnet brings up the vmnet bridge that sanctum-vm rides on; com.sanctum.vm-autostart starts the Lima VM at login. The guest’s OpenClaw gateway comes up on :1977 and is forwarded to host loopback.

Phase 2: Container Orchestration

com.sanctum.openclaw.docker-startup (a LaunchAgent) runs ~/.openclaw/launch-after-docker.sh. The script polls the OrbStack Docker socket (~/.orbstack/run/docker.sock) every 2s for up to 120s, reaps orphans from any previous compose config (docker compose down --remove-orphans, so a stale container can’t squat on a port the new one wants), then brings the ancillary stack up. OpenClaw itself is already live in the VM — the script does not start it.

Phase 3: Privileged Daemons

The host’s privileged set lives in /Library/LaunchDaemons/: com.sanctum.pfctl (the pf driver), com.sanctum.vmnet (the VM bridge), com.sanctum.castellan plus com.sanctum.castellan-deadman (the supervisor and its dead-man’s switch), com.sanctum.watchdog-rust, com.sanctum.force-flow, com.sanctum.proxyd, and the HA / Firewalla gateways. There is no net-filter or hw-sync daemon; those were never built.

Security Model

The Sanctum operates on Zero-Trust Isolation: no component is trusted by default, and every interaction is mediated. For the broader posture, see Security.

Secrets Management

Secrets live in the trifecta, not in plaintext on the host’s disk: 1Password (human source of truth) → VM SOPS (agents) → Mini Keychain (host tools). Shell loaders under ~/.sanctum/secrets/ (mode 600, never committed) hand env vars to the services that need them — proxyd reads its provider keys this way. A scheduled com.sanctum.rotate-secrets job mints fresh values and a drift sentinel reconciles the three stores. See Secrets Trifecta and Secret Rotation.

Danger

If the drift check finds the three stores out of sync and can’t reconcile, it alerts via Force Flow rather than papering over it. This is not a bug — it’s the system choosing an honest red flag over running on credentials it can’t prove are current. Hoping for the best is not a strategy.

Network Isolation

OpenClaw lives behind the bridge100 vmnet interface inside the guest; nothing on the LAN routes to it. Host traffic is governed by pf (driven by com.sanctum.pfctl), and every host service that matters binds to 127.0.0.1 — signal-cli (:8080), the coder MLX (:3301), the Sanctum Bridge (:8443). The mTLS MLX path on :1337 is the one that also answers on Tailscale, and it validates certs first. If you don’t have a valid cert, you don’t get in. The bouncer doesn’t care about your feelings.

The OpenClaw core is sandboxed by the VM boundary itself — a separate Linux kernel, its own filesystem, no Metal except through the loopback MLX ports. The host daemons run under launchd with the privilege each one needs and no more.

Failure Modes and Self-Healing

The system degrades gracefully and recovers without human intervention. Most of the time. The rest of the time, it tells you exactly what went wrong and waits while you fix it.

Component Recovery Matrix

Component	Failure Mode	Detection	Self-Healing Action
Host daemons	Crash / non-zero exit	launchd KeepAlive	Immediate respawn; castellan supervises and castellan-deadman is the backstop if the supervisor itself dies
sanctum-vm (OpenClaw)	VM stop / hang	Health poll on :1977	com.sanctum.vm-autostart restarts the guest; sentinels alert if it stays down
OrbStack engine	Docker socket unreachable	launch-after-docker.sh socket poll + com.sanctum.orbstack-engine-autostart	Engine restart, then ancillary stack brought back up
Stuck / crash-looping job	Job spins or wedges	launchd-health-sentinel (every 600s)	Surfaces to the chitti log; the r2d2 recipe layer auto-fixes known patterns
Any red-tier condition	Live exposure / broken auto-immune	Sentinel fleet under ~/.sanctum/sentinels/	Pages the operator via Force Flow; ambient state stays in logs

The Sentinel Fleet, Not a Circuit Breaker

Recovery is a layer, not a switch. launchd KeepAlive respawns crashed daemons; the sentinel fleet under ~/.sanctum/sentinels/ watches the parts launchd can’t see and escalates only on a real red-tier condition; r2d2 auto-fires vetted fix recipes for the failures it recognizes.

This is deliberate. The system would rather fix the failure it understands and page a human for the one it doesn’t, than thrash forever pretending every problem is the same. It’s the infrastructure equivalent of knowing when to ask for help.

Data Integrity

Host logs rotate under /var/log/sanctum/ and ~/.openclaw/logs/ via com.sanctum.log-rotate. OpenClaw’s application state lives inside the VM’s disk image, which the host’s restic backups capture. If a restore is ever needed, see Backup & Restore.

---

The host holds the hardware. The VM holds the logic. The proxy holds the door. So it is decreed.