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 checks in order:

   • Configuration validation (instance.yaml syntax, required keys)
   • Node identity verification (.node_id exists and matches config)
   • LaunchAgent status (loaded and running)
   • Service health (port reachability, HTTP endpoints)
   • VM connectivity (SSH, bridge network)
   • Dashboard availability

2. Review the output.

   Each check prints a status line:

   [PASS] instance.yaml is valid
   [PASS] node_id "your-haus-name" matches config
   [PASS] com.sanctum.gateway is running
   [PASS] Gateway responding on port 1977
   [FAIL] com.sanctum.voice-agent 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

You can run individual test groups by passing a filter argument. For example, bash ~/.sanctum/tests/run-all.sh services runs only the service health checks. Useful when you know exactly which thing you broke.

Verify LaunchAgents

Check that all expected Sanctum LaunchAgents are loaded and running.

launchctl list | grep sanctum

You should see entries for each enabled service. A typical hub node might show:

-     0     com.sanctum.gateway
-     0     com.sanctum.dashboard
-     0     com.sanctum.homeassistant
-     0     com.sanctum.firewalla-bridge
-     0     com.sanctum.voice-agent
-     0     com.sanctum.utm-autostart
-     0     com.sanctum.watchdog
-     0     com.sanctum.cloudflare-tunnel

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.

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 LaunchAgents log to the system log
log show --predicate 'process == "sanctum"' --last 5m

# Or check the specific stdout/stderr files defined in the plist
cat /tmp/com.sanctum.<service>.stdout.log
cat /tmp/com.sanctum.<service>.stderr.log

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://your-haus-name

2. Verify service status.

   The dashboard haus screen shows the health of all enabled services. 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, your-haus-name). Verify that it matches a key in the nodes section of instance.yaml:

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 10.10.10.1 assigned to the interface. If the interface does not exist, verify that UTM is running and the VM is started.

2. Test SSH.

   ssh [email protected] 'hostname && uptime'

   This should print the VM hostname and uptime without prompting for a password (assuming SSH key auth is configured).

3. Check VM services.

   ssh [email protected] 'systemctl --user status sanctum-gateway'

   The gateway service on the VM should show active (running).

Enable the Watchdog

The watchdog monitors all services and performs automatic remediation when it detects failures. It runs on a timer (default: every 10 minutes) and is managed by its own LaunchAgent. Think of it as a night nurse for your infrastructure — quietly checking pulses, administering medicine, only paging you when someone flatlines.

Verify the watchdog is loaded:

launchctl list | grep com.sanctum.watchdog

The watchdog writes a health report after each run. Check the latest report:

cat /tmp/sanctum-watchdog-latest.log

Caution

The watchdog will attempt to restart failed services automatically. If you are still in the process of configuring services, you may want to delay loading the watchdog LaunchAgent until your initial setup is complete. Otherwise it will helpfully restart the thing you are actively trying to configure, creating 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 you have a watchdog for that 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.