First Run

After completing the Installation, follow this guide to verify that everything is running correctly and complete the initial setup. This is the part where you find out whether your confidence was justified or merely aspirational.

Run the Test Suite

Sanctum includes a test suite that validates your configuration, checks service health, and reports any issues. It is honest. Sometimes brutally so.

1. Execute the full test suite.

   bash ~/.sanctum/tests/run-all.sh

   The suite runs config-library checks, LaunchAgent and instance.yaml validation, cron and model-scout checks, the connection suite (ports, HTTP endpoints, keychain keys), every skill’s own tests, and the two dashboard vitest suites. The connection suite is the one that tells you whether your services are actually answering.

2. Review the output.

   Each check in the connection suite prints a status line:

   ✓ PASS instance.yaml is valid
   ✓ PASS node_id "manoir" matches config
   ✓ PASS com.sanctum.dashboard is running
   ✓ PASS Dashboard responding on port 1111
   ✗ FAIL com.sanctum.force-flow is not running

   A wall of ✓ PASS is a beautiful thing. Address any ✗ FAIL lines before continuing. Do not skip them. Do not convince yourself they are probably fine. They are not fine.

3. Re-run after fixes.

   If you needed to fix anything, run the suite again to confirm a clean pass:

   bash ~/.sanctum/tests/run-all.sh

Tip

The runner takes one flag, --quiet, which collapses each suite to its summary line: bash ~/.sanctum/tests/run-all.sh --quiet. Handy on a healthy box, when you want the verdict without the wall of green. There is no per-group filter — to run just one suite, invoke its script directly, e.g. bash ~/.sanctum/tests/test-connections.sh.

Verify LaunchAgents

Check that all expected Sanctum LaunchAgents are loaded and running.

launchctl list | grep sanctum

You should see entries for each enabled service. The list grows as you add agents and tunnels; a hub node will show dozens. A representative slice:

-     0     com.sanctum.dashboard
-     0     com.sanctum.vm-autostart
-     0     com.sanctum.r2d2
-     0     com.sanctum.presence
-     0     com.sanctum.memory-vault
-     0     com.sanctum.force-flow
-     0     com.sanctum.mlx
-     0     com.sanctum.tunnel
-     0     com.sanctum.backup

The second column is the exit status. A 0 indicates the service exited cleanly (or is still running). A non-zero value suggests a startup failure, which is macOS’s polite way of saying something went wrong and it will not be telling you what. (Some labels carry a negative number like -15 — that is the signal that stopped them, not a failure; -15 is a clean SIGTERM from a KeepAlive restart.)

Troubleshooting

If a LaunchAgent is missing from the list, load it manually:

launchctl load ~/Library/LaunchAgents/com.sanctum.<service>.plist

If it exits immediately with a non-zero status, check its log output. Most Sanctum agents redirect stdout and stderr to a file under ~/.openclaw/logs/ — the exact path is the StandardOutPath / StandardErrorPath in the plist:

# The convention is ~/.openclaw/logs/<service>.log (+ .err for stderr)
tail -50 ~/.openclaw/logs/<service>.log

# Confirm the exact paths from the plist itself
plutil -p ~/Library/LaunchAgents/com.sanctum.<service>.plist \
  | grep -E 'StandardOutPath|StandardErrorPath'

The unified system log is a poor first stop here: Sanctum binaries run under their own names (castellan, proxyd, sanctum-mlx, force_flow.py), not a process literally called sanctum, so --predicate 'process == "sanctum"' matches nothing. Read the plist’s log file first.

Common Issues

Symptom	Cause	Fix
Agent not in list	Plist not loaded	launchctl load ~/Library/LaunchAgents/com.sanctum.*.plist
Exit status 78	Configuration error	Check instance.yaml for the affected service
Exit status 127	Binary not found	Verify node, python3, or other binaries are in the plist PATH
Agent loads but port unreachable	Firewall or binding issue	Check if another process is using the port with lsof -i :<port>

Note

Exit status 78 is EX_CONFIG in sysexits.h. It means the program found its configuration unacceptable and politely refused to start. Exit status 127 means it could not find the binary at all, which is less polite and usually means your PATH is wrong in the plist environment.

Open the Dashboard

Navigate to the dashboard in your browser. This is the reward for all that terminal work.

1. Access the dashboard.

   http://localhost:1111

   If you configured a hostname alias (such as a DNS entry or mDNS broadcast), you can use that instead:

   http://manoir.local:1111

2. Verify service status.

   The root page serves the Command Center — the browser tab title reads “your instance name Command Center”. The same backend feeds both the tiles and the /api/config endpoint below. Each service tile displays:

   • Service name and port
   • Status indicator (green = healthy, red = down, yellow = degraded)
   • Uptime since last restart

   If everything is green, take a screenshot. Show someone. You have earned this.

3. Check the config endpoint.

   Confirm the dashboard is reading your configuration correctly:

   curl -s http://localhost:1111/api/config | python3 -m json.tool

   The response should include your instance name, slug, and the list of enabled services. Secrets are excluded from this endpoint.

Verify Node Identity

Confirm that your node identity is correctly configured.

cat ~/.sanctum/.node_id

This should print the slug you set during installation (for example, manoir). Verify that it matches a key in the nodes section of instance.yaml. sanctum_get is a shell function in ~/.sanctum/lib/config.sh, not a binary on your PATH, so source the library first:

source ~/.sanctum/lib/config.sh
sanctum_get nodes.$(cat ~/.sanctum/.node_id).type

This should print hub for a hub node. If the command returns nothing or an error, double-check that your .node_id value matches the YAML key exactly. YAML does not forgive typos. YAML does not forgive anything.

Verify VM Connectivity

If you set up the Ubuntu VM, confirm the Mac-to-VM link is working. This is where two machines learn to trust each other across a private network that only they know about.

1. Check the bridge interface.

   ifconfig bridge100

   You should see the Mac-side bridge address (10.0.0.1 in the default config) assigned to the interface. If the interface does not exist, confirm the Lima VM is up — LIMA_HOME=$HOME/.lima limactl list should show sanctum-vm as Running; if not, start it with limactl start sanctum-vm --tty=false. Also confirm socket_vmnet is running (brew services list | grep socket_vmnet should say started), since the host-only bridge depends on it.

2. Test SSH.

   ssh openclaw 'hostname && uptime'

   openclaw is the SSH alias the installer writes for the VM (it resolves to the bridge address, 10.0.0.10 by default). This should print the VM hostname and uptime without prompting for a password, assuming SSH key auth is configured.

3. Check VM services.

   The gateway on the VM runs under pnpm as a user systemd unit named openclaw-gateway — not sanctum-gateway:

   ssh openclaw 'systemctl --user status openclaw-gateway'

   It should show active (running). Its two siblings, yoda-chat-consumer and yoda-chat-proxy, carry the Signal channel; check them the same way if voice or messaging is quiet.

Verify the Remediation Loop

Automatic remediation is handled by R2D2 (com.sanctum.r2d2), which runs on a timer every 600 seconds. It does not blindly restart things: each cycle it detects notices, classifies them through a small LLM (Hermes) against a registry of vetted repair recipes, fires only the ones whose blast radius is safe, and audits the result. Think of it as a night nurse who reads the chart before reaching for the medicine — and pages you instead when the fix is above their pay grade.

Verify it is loaded:

launchctl list | grep com.sanctum.r2d2

R2D2 writes one JSON line per cycle. Tail the log to see what it considered and what it fired (or skipped on cooldown):

tail -5 ~/.openclaw/logs/r2d2.log

The durable audit trail — every recipe that actually fired — lives at ~/.sanctum/logs/r2d2-audit.jsonl.

Caution

R2D2 only fires recipes whose blast radius is bounded, and most repairs sit behind a cooldown so it cannot fight you in a loop. Still, if you are mid-configuration on a service it knows a recipe for, expect it to “help.” You can pause it during setup by booting it out (launchctl bootout gui/$(id -u)/com.sanctum.r2d2) and bring it back when you are done — restarting the thing you are actively trying to configure is the kind of debugging loop that erodes a person’s will to live.

What Comes Next

With a verified installation, you are ready to start using Sanctum. The hard part is over. (That was a lie. The hard part is maintenance. But R2D2 takes the night shift now.)

Here are recommended next steps:

• Architecture Overview — Understand how the platform components fit together.
• Configure agents — Set up AI agents for security, efficiency, health, and finance.
• Add a satellite node — Extend the platform to a second location.
• Set up secret rotation — Enable automatic monthly token rotation.
• Customize the dashboard — Add or remove panels based on your enabled services.