Installation

This is the detailed install reference. If you’ve never set up Sanctum before and you want the friendly 4-step version, start with Quick Start — it’s the same canonical flow, just terser.

This page goes deeper: full troubleshooting for the steps that occasionally go sideways, a verification protocol you can run after install, and an operator-grade appendix for people running Sanctum from source rather than from the published binary.

The canonical install path

Sanctum’s public install path is the Homebrew tap at Ogilthorp3/homebrew-sanctum. The tap installs the sanctum-cli Python application, which then orchestrates everything else (cloud backup setup, first backup, restore canary, all of it).

1. Install Homebrew if you don’t already have it.

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   Homebrew installs into /opt/homebrew/ and will ask for your administrator password once during the install. That prompt is from Apple’s installer, not Homebrew — it needs to create directories under /opt/. After it finishes, run brew --version to confirm; you should see something like Homebrew 5.x.x.

   Tip

   On a brand-new Mac, the first time you run brew install Homebrew may also prompt you to install Apple’s Command Line Tools. Let it. That’s a one-time macOS thing and Apple does it from System Settings → Software Update if your Mac doesn’t have them yet.

2. Install sanctum-cli via the Homebrew tap.

   brew install ogilthorp3/sanctum/sanctum-cli

   This installs Python 3.12 (if you don’t already have it), creates a private virtual environment under Homebrew’s libexec, pulls sanctum-cli v0.8.0 plus its 38 runtime Python dependencies from PyPI, and symlinks the sanctum command into /opt/homebrew/bin/sanctum.

   Confirm:

   sanctum --help

   You should see a help screen listing the available sub-commands (status, doctor, onboard, backup, chat, agent, proxy, bridge, cloud, code, config, keychain, vision).

3. Run the one-shot onboarding flow.

   sanctum onboard --recipe family

   The family recipe is the right pick for a new haus. It pulls a curated backup set (Documents, Desktop, ssh keys, dotfiles — about 5 GB after dedup), walks you through Cloudflare R2 cloud-bucket setup if you don’t have one yet, runs a dry-run backup so you can see exactly what will happen, executes the real backup, and verifies the round-trip by restoring a known file as a canary.

   When it finishes, you’ll see a green panel that says “Your Sanctum is alive, <your name>.” That’s the moment.

   Note

   Other available recipes:

   • operator — for an experienced operator setting up a hub Mac Mini with the full sanctum stack (broader backup scope, no Photos auto-exclude)
   • code — for a developer machine (Documents, dotfiles, ssh keys, plus ~/Projects)
   • Or pass a path to a JSON file with custom paths.

4. Verify the install.

   sanctum status        # one-line health snapshot
   sanctum doctor        # full diagnostic

   status should print a single line ending in green text. doctor runs deeper checks: each cloud backend, the Keychain credentials, the LaunchAgent that runs daily backups, and the network paths. Everything green is the goal.

What you just got

What	Where	How long it lasts
Daily backups (verified)	com.sanctum.backup LaunchAgent runs at a quiet hour	Forever, automatic
Restore canary (proves round-trip works)	Same LaunchAgent, weekly	Forever, automatic
Health snapshot command	sanctum status	On-demand
Deep diagnostic	sanctum doctor	On-demand
Local agent chat	sanctum chat	On-demand
Audit log of every action	~/.sanctum/logs/ with bounded rotation	Bounded at 50 MB per service
Credentials in macOS Keychain	security find-generic-password -s sanctum/...	Until you rotate them

No phone-home. Nothing leaves your Mac unless you explicitly configured a cloud backup target (which you did, for backups, encrypted with a key only you control).

When something goes sideways

The honest truth is most install runs work first time. The ones that don’t usually hit one of these.

”Your Command Line Tools are too outdated”

brew install checks for Xcode’s Command Line Tools and refuses to build dependencies if they’re missing or stale.

# Check what's installed
xcode-select -p
pkgutil --pkg-info=com.apple.pkg.CLTools_Executables

# Install or update
sudo xcode-select --install

If the install dialog doesn’t appear, open System Settings → Software Update — Apple sometimes routes CLT updates through the regular macOS Update path.

”Cloudflare R2 setup failed”

The R2 wizard opens browser tabs for the steps that need your input (account creation, API token generation, bucket creation). If a browser tab didn’t open or you cancelled it partway, re-run:

sanctum cloud setup r2

The wizard is idempotent — it picks up where you left off. If R2 is being slow to provision (rare but real), wait a few minutes and try sanctum doctor again.

”Permission denied (publickey)”

This shows up if you ran sanctum onboard while signed into a different Mac account, or with sudo (don’t). Sanctum stores its credentials in your user-level Keychain. Make sure you’re running as your normal user, not root.

”The brew tap failed to clone”

If brew install ogilthorp3/sanctum/sanctum-cli errors with something about Git LFS or a cloning failure, your global Git hooks may be blocking the clone. Check:

git config --global core.hookspath

If that returns a custom path, the hooks in that directory need to soft-fail when their tools aren’t found. See sanctum-runtime post-checkout hook for the canonical pattern.

”Permissions prompts every time I run sanctum”

If you keep seeing macOS permission dialogs (“node would like to access X”), the canonical fix lives in runbooks/node-tcc-stop-the-prompts.md. Short version: install the Node.js Foundation .pkg from nodejs.org/dist/, migrate sanctum services to /usr/local/bin/node, and grant Full Disk Access once. The runbook has the script that automates all 13 grants.

What’s next

If everything looks green:

• Read the First Run page for the verification checklist (it’s the same sanity-check the daily LaunchAgent runs, on demand)
• Read What Is Sanctum? if you want context on the why
• Browse the architecture pages if you want to know how it works under the hood
• For sharing the haus with family members, see Family Pass installation (v1.0 is in active implementation — the operator path works today)

If something is failing:

• sanctum doctor and read the output carefully
• Audit log at ~/.sanctum/logs/ for the failing service
• Troubleshooting page has copy-pastable fixes for the top 10 issues
• Open an issue on the relevant GitHub repo

---

Appendix — Operator-grade install (running from source)

If you’re an operator running Sanctum from the source tree rather than the published binary — typically because you’re hacking on it — there’s a separate flow that installs the full audit-wall toolchain and the checked-in renderers.

Tip

You almost certainly do not want this if you’re just trying Sanctum out. The brew install path above gives you the full beta-tester experience. The source-install path is for active contributors.

The legacy sanctumctl operator CLI is what older docs reference. It still exists, but its consumers are mostly the daily audit-wall and the release-discipline gate (tools/sanctum-release.sh), not new users. If you’re maintaining a fork or building from a tag, that’s the path:

# From inside the checked-in workspace
python3 tools/sanctumctl.py bootstrap --write   # writes the ~/.sanctum scaffold
python3 tools/sanctumctl.py doctor              # runs the audited verification wall

That flow creates the ~/.sanctum scaffold, drops in the annotated instance.yaml.example, writes a node identity file, and runs the audited verification wall. Inspect-before-write is bootstrap without --write.

The manual section that used to live here (mkdir, cp, hand-editing instance.yaml, generating LaunchAgents one by one) is preserved in git history if you need it for a deep-debugging scenario, but the canonical operator path is sanctumctl bootstrap --write followed by sanctumctl doctor. The same instance.yaml schema, the same ~/.sanctum layout — just driven by the audit-wall renderer instead of by hand.