LaunchAgents & LaunchDaemons

Sanctum manages a set of macOS LaunchAgents (user-level) and LaunchDaemons (root-level) that form the boot chain for the haus intelligence platform. Each plist is rendered from templates at ~/.sanctum/templates/launchagents/ by the generate-plists.sh script, which pulls values from instance.yaml and tokens from the macOS Keychain.

You might wonder why these aren’t written in a friendlier format. The answer is that Apple chose XML for process management configuration in 2005 and has been politely pretending that was fine ever since. The template system exists so you never have to touch raw plist XML. You’re welcome.

Tip

Services with KeepAlive: true are automatically restarted by launchd if they exit. Services without KeepAlive run once at load and are not restarted. KeepAlive is the difference between “runs at boot” and “runs forever, whether it likes it or not.”

Boot Chain Overview

LaunchAgents are loaded at user login. The ordering below reflects the logical dependency chain — launchd does not guarantee ordering, but RunAtLoad: true ensures all agents start promptly after login.

In practice, everything starts within seconds of each other and sorts itself out. It’s less of a chain and more of a stampede in roughly the right direction.

LaunchAgents

Core Infrastructure

These agents stand up the VM, the gateway, and the firewall bridge. Without them, the rest of the stack is a collection of orphaned processes with nowhere to send their feelings.

com.sanctum.utm-autostart

Property	Value
Label	com.sanctum.utm-autostart
Purpose	Launch UTM, start the VM, and set the bridge100 IP to the configured mac_bridge_ip
Required Service	vm
KeepAlive	No
RunAtLoad	Yes

Runs a startup script that launches UTM.app, waits for the VM to boot, and configures the bridge interface IP via sudo ifconfig. Requires the vmnet-bridge sudoers entry at /etc/sudoers.d/vmnet-bridge.

The first domino. Everything else assumes the VM is running and the bridge exists. If this one fails, enjoy your very expensive space heater.

---

com.sanctum.gateway

Property	Value
Label	com.sanctum.gateway
Purpose	OpenClaw/DenchClaw agent gateway on the Mac side
Required Service	gateway
KeepAlive	No
RunAtLoad	Yes
Port	1977

The Mac-side agent gateway. Uses /opt/homebrew/bin/node (stable Homebrew symlink, not a versioned Cellar path) because pointing a LaunchAgent at a Cellar path is a time bomb with a brew upgrade fuse.

Caution

Always restart via openclaw gateway stop and openclaw gateway start. Never use raw launchctl commands for this service — the CLI handles state cleanup. Ignoring this advice results in orphaned port locks and a gateway that thinks it’s running when it isn’t, which is worse than a gateway that’s honestly down.

---

com.sanctum.firewalla

Property	Value
Label	com.sanctum.firewalla
Purpose	Bridge between the Sanctum stack and the Firewalla Purple router via the P2P API
Required Service	firewalla
KeepAlive	Yes
RunAtLoad	Yes
Port	1984
Bind	0.0.0.0 (accessible from VM)

Runs firewalla-bridge.js which authenticates to Firewalla’s cloud endpoint and then communicates locally over port 8833. The bridge binds to all interfaces so the VM can reach it at 10.10.10.1:1984.

A bridge to a bridge. Networking is turtles all the way down.

---

AI & Voice

The agents that give the house its opinions. One serves a 27-billion-parameter model. One synthesizes speech. One listens for a wake word and responds as a fictional Jedi. Totally standard residential infrastructure.

com.sanctum.xtts-server

Property	Value
Label	com.sanctum.xtts-server
Purpose	XTTS-v2 text-to-speech server using Mac GPU (MPS)
Required Service	xtts
KeepAlive	No
RunAtLoad	Yes

Provides TTS capability for the voice agent. Runs on the Mac to leverage Metal Performance Shaders — because asking a CPU to synthesize speech in real time is like asking a poet to take dictation. It can do it. It won’t enjoy it.

---

com.sanctum.voice-agent

Property	Value
Label	com.sanctum.voice-agent
Purpose	Yoda voice interaction agent
Required Service	voice_agent
KeepAlive	No
RunAtLoad	Yes

Manages voice capture, wake-word detection, and Yoda personality interactions. A daemon that sits in silence, waiting for someone to speak, then answers in the cadence of a small green Jedi master. Your house does this now. You chose this life.

---

com.sanctum.idle-mlx

Property	Value
Label	com.sanctum.idle-mlx
Purpose	Council-27B MLX model server for local agent inference
Required Service	mlx_server
KeepAlive	Yes
RunAtLoad	Yes
Port	1337

Serves the Qwen3.5-27B-4bit model with a LoRA adapter supporting 6 agent personalities. KeepAlive ensures the model stays loaded in memory. Twenty-seven billion parameters, sitting in RAM, waiting to be useful. The idle power draw of a small space heater, but for thinking.

---

com.sanctum.proxy

Property	Value
Label	com.sanctum.proxy
Purpose	Sanctum Proxy — single-binary LLM routing layer
Required Service	proxy
KeepAlive	Yes
RunAtLoad	Yes
Port	4040 (all interfaces)

A single Rust binary that handles the full LLM request pipeline: request sanitization, content-based routing, prompt caching, PII scrubbing, assistant prefill stripping, model resolution, tiered fallback chains, and analytics. All agent traffic enters through port 4040. The bouncer and the bartender in one efficient package.

---

Network & Tunnels

Every system with a VM that can’t see the LAN eventually grows a small collection of tunnels. This is that collection. Each one exists because some process needed to reach some other process, and a direct route was too much to ask.

com.sanctum.ha-tunnel

Property	Value
Label	com.sanctum.ha-tunnel
Purpose	SSH tunnel from the HA Docker container to the VM’s Network Control API on port 4007
Required Service	home_assistant
KeepAlive	No
RunAtLoad	Yes

Allows the Home Assistant container (running in Docker bridge networking) to reach the VM’s Network Control API via host.docker.internal. A Docker container, talking through an SSH tunnel, to a VM it can’t see, about devices on a network it’s not on. Distributed systems are just loneliness at scale.

---

com.sanctum.health-tunnel

Property	Value
Label	com.sanctum.health-tunnel
Purpose	SSH tunnel for the health ingester to reach the VM on port 10101
Required Service	health_center
KeepAlive	Yes
RunAtLoad	Yes

The health ingester’s lifeline to the VM. Keeps itself alive because health data waits for no one — your resting heart rate doesn’t care that the tunnel crashed at 3 AM.

---

com.sanctum.tunnel

Property	Value
Label	com.sanctum.tunnel
Purpose	Cloudflare Zero Trust tunnel for external access
Required Service	cloudflare
KeepAlive	Yes
RunAtLoad	Yes

Runs the cloudflared tunnel daemon for the configured tunnel name (e.g., manoir-nepveu). Routes external traffic to internal services like Home Assistant and the health ingester. The one tunnel in this list that actually reaches the outside world, which makes it either the most important or the most dangerous, depending on your threat model.

---

com.sanctum.orbi-bridge

Property	Value
Label	com.sanctum.orbi-bridge
Purpose	socat bridge allowing the VM to reach the Orbi router
Required Service	vm
KeepAlive	Yes
RunAtLoad	Yes
Ports	18080 (HTTP), 18085 (API)

Forwards VM traffic from 10.10.10.1:18080 to the Orbi router at 192.168.1.2:80 and 10.10.10.1:18085 to 192.168.1.2:5000. Required because the VM has no direct LAN access.

The VM wants to talk to the router. The VM can’t reach the router. So we built a socat tunnel through the Mac. Networking: where every problem is solved by adding another layer of indirection.

---

com.sanctum.signal-bridge

Property	Value
Label	com.sanctum.signal-bridge
Purpose	Signal messaging bridge for agent communication
Required Service	signal_bridge
KeepAlive	Yes
RunAtLoad	Yes

Lets agents send and receive Signal messages. End-to-end encrypted AI communication — because if your house is going to text you, it should at least have the decency to do it privately.

---

System & Maintenance

The quiet ones. They file your documents, rotate your secrets, watch for fires, and serve your offline Wikipedia. They don’t get thanked enough.

com.sanctum.icloud-filer

Property	Value
Label	com.sanctum.icloud-filer
Purpose	Automatic filing daemon for iCloud Drive documents
Required Service	icloud_filer
KeepAlive	Yes
RunAtLoad	Yes

Watches iCloud Drive directories and automatically files documents into organized folder structures. Digital Marie Kondo, but for PDFs. Does it spark joy? Doesn’t matter. It sparks organization.

---

com.sanctum.watchdog

Property	Value
Label	com.sanctum.watchdog
Purpose	Health monitoring watchdog that runs every 600 seconds
Required Service	watchdog
KeepAlive	No
RunAtLoad	Yes
StartInterval	600

Periodically checks the health of all enabled services and auto-heals failures via service-doctor. Not KeepAlive — uses launchd’s StartInterval for periodic execution. Every ten minutes, it wakes up, looks around, makes sure nothing is on fire, and goes back to sleep. The most relatable agent in the fleet.

---

com.sanctum.rotate-secrets

Property	Value
Label	com.sanctum.rotate-secrets
Purpose	Monthly secret rotation (gateway tokens, API keys)
Required Service	—
KeepAlive	No
RunAtLoad	No
StartCalendarInterval	1st of each month at 03:30

Runs on a calendar schedule, not at boot. Rotates secrets stored in 1Password and the macOS Keychain. The only agent that doesn’t start at login — it waits for its appointed hour like a well-mannered assassin.

---

com.sanctum.dashboard

Property	Value
Label	com.sanctum.dashboard
Purpose	Command center dashboard web server
Required Service	dashboard
KeepAlive	No
RunAtLoad	Yes
Port	1111

The dashboard. Where you go to see, at a glance, whether the twenty-odd processes described on this page are all still speaking to each other. Think of it as mission control, except the mission is “keep the house sentient.”

---

com.sanctum.kiwix-serve

Property	Value
Label	com.sanctum.kiwix-serve
Purpose	Kiwix offline library server (Wikipedia, etc.)
Required Service	kiwix
KeepAlive	Yes
RunAtLoad	Yes
Port	8888
ThrottleInterval	30

Requires an external T9 drive to be mounted. KeepAlive with ThrottleInterval prevents rapid restart loops if the drive is disconnected. All of human knowledge, served from an external hard drive — the library of Alexandria, if Alexandria ran on USB-C.

Note

Without the T9 drive, Kiwix starts, fails, waits 30 seconds, starts, fails, waits 30 seconds — forever. This is launchd’s version of patience. The ThrottleInterval keeps it from consuming your Mac’s entire CPU in a panicked loop of optimism.

---

LaunchDaemons

Everything above runs as your user. Everything below runs as root. There is exactly one daemon in this section, and it exists because of a number: 80. The lowest-numbered privilege escalation in the history of home automation.

com.sanctum.dench-proxy

Property	Value
Label	com.sanctum.dench-proxy
Purpose	Reverse proxy from port 80 to port 1977 for the Holocron chat interface
Required Service	gateway
KeepAlive	Yes
RunAtLoad	Yes
Runs as	root

This is a LaunchDaemon (not a LaunchAgent) because binding to port 80 requires root privileges. It enables http://holocron/ access from the LAN without specifying a port.

Plist location: /Library/LaunchDaemons/com.sanctum.dench-proxy.plist

The entire reason this runs as root is so family members can type holocron into a browser instead of holocron:1977. Usability has a cost. That cost is sudo.

---

Plist Generation

All plists are rendered from Mustache-style templates using values from instance.yaml and tokens from the macOS Keychain:

# Preview what would be generated (dry run)
~/.sanctum/generate-plists.sh --dry-run

# Generate and install all plists for enabled services
~/.sanctum/generate-plists.sh

The generator:

1. Reads each template from ~/.sanctum/templates/launchagents/
2. Checks if the corresponding service is enabled in instance.yaml
3. Expands {{PLACEHOLDER}} tokens with config values
4. Pulls secrets from the macOS Keychain using the configured keychain_account
5. Writes the rendered plist to ~/Library/LaunchAgents/ (or /Library/LaunchDaemons/ for daemons)

---

Managing Agents

Load or unload agents using launchctl:

# Load an agent
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.sanctum.watchdog.plist

# Unload an agent
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.sanctum.watchdog.plist

# Check if an agent is running
launchctl print gui/$(id -u)/com.sanctum.watchdog

Caution

The gateway (com.sanctum.gateway) should always be managed via openclaw gateway start/stop, not via raw launchctl commands. The CLI handles cleanup of state files and port locks. This is the third time these docs have told you this. There will not be a fourth.