Installation

Quick Install

Open Terminal and run:

curl -fsSL https://sanctum.run/install.sh | bash

The installer checks your hardware, installs dependencies, walks you through configuration, and sets up your Sanctum — all in about two minutes. No manual YAML editing required.

Tip

Prefer to inspect before running? Download first: curl -fsSL https://sanctum.run/install.sh -o install.sh && less install.sh && bash install.sh

The installer will:

1. Verify your Mac meets the requirements (Apple Silicon, macOS 15+, 16GB+ RAM)
2. Install missing dependencies (Homebrew, Node.js, Python, Docker) with your permission
3. Ask you a few questions about your home and which features you want
4. Create ~/.sanctum/instance.yaml with your configuration
5. Start the Presidio privacy containers (PII scrubbing for external AI)
6. Set up the shell library and LaunchAgents

After installation, visit the First Run guide to verify everything is working.

---

Manual Installation

If you prefer to set things up by hand, follow the steps below. Make sure you have completed all the Requirements first.

Create the Sanctum Home Directory

1. Create the directory structure.

   Sanctum stores all configuration, templates, and runtime data under ~/.sanctum.

   mkdir -p ~/.sanctum/{templates/launchagents,tests,lib,scripts}

2. Copy the example configuration.

   The example file is an annotated template that documents every available option.

   cp ~/.sanctum/instance.yaml.example ~/.sanctum/instance.yaml

   Tip

   If you are setting up from a fresh clone, the example file is included in the Sanctum repository under config/instance.yaml.example.

3. Set your node identity.

   Each node needs a single-line identity file that tells the system which node it is.

   echo "your-home-name" > ~/.sanctum/.node_id

   Use a short, lowercase slug. This value must match a key under the nodes section of your instance.yaml.

Configure instance.yaml

Open ~/.sanctum/instance.yaml in your editor. The file is organized into these top-level sections:

# Instance identity
instance:
  name: "Your Home Name"
  slug: "your-home-name"

# Node topology
nodes:
  your-home-name:
    type: hub
    host: 192.168.1.10
    # ...

# Services and their ports
services:
  gateway:
    enabled: true
    port: 18789
  homeassistant:
    enabled: true
    port: 8123
  # ...

# VM configuration
vm:
  ip: 10.10.10.10
  bridge_ip: 10.10.10.1
  ssh_user: ubuntu
  # ...

# Secret management
secrets:
  backend: keychain  # "keychain" on Mac, "sops" on VM
  rotation_day: 1    # Day of month for auto-rotation

Caution

Do not put actual secrets (API keys, tokens, passwords) in instance.yaml. The config file references secret names that are resolved at runtime from macOS Keychain or SOPS-encrypted files. See the Secrets Management guide for details.

Key Sections to Edit

At minimum, configure the following for your environment:

Section	What to Set
instance.name	Human-readable name for your home
instance.slug	URL-safe lowercase slug
nodes	At least one hub node with its LAN IP
services	Enable or disable services based on what you need
vm.ip	Your VM’s static IP (default: 10.10.10.10)

Install the Shell Library

The shell library provides helper functions used by scripts and LaunchAgents.

1. Source the library in your shell profile.

   Add this line to your ~/.zshrc (or ~/.bashrc):

   source ~/.sanctum/lib/config.sh

2. Reload your shell.

   source ~/.zshrc

3. Verify the library is loaded.

   sanctum_get instance.slug

   This should print your instance slug. If it does, the config library is working.

The shell library provides these functions:

Function	Purpose
sanctum_get <key>	Read a value from instance.yaml
sanctum_slug	Shortcut for the instance slug
sanctum_home	Returns the Sanctum home directory path
sanctum_vm_ssh <command>	Run a command on the VM via SSH
sanctum_enabled <service>	Check if a service is enabled
sanctum_expand <template>	Expand {{PLACEHOLDER}} variables in a template

Generate LaunchAgents

Sanctum uses macOS LaunchAgents to manage services. Rather than maintaining individual plist files by hand, you generate them from templates.

1. Review the templates.

   Templates live in ~/.sanctum/templates/launchagents/. Each template uses {{PLACEHOLDER}} syntax for values pulled from instance.yaml and macOS Keychain.

2. Run the generator.

   # Preview what will be generated (no files written)
   bash ~/.sanctum/generate-plists.sh --dry-run
   
   # Generate for real
   bash ~/.sanctum/generate-plists.sh

   The generator does the following:

   • Reads each template from ~/.sanctum/templates/launchagents/
   • Expands placeholders with values from instance.yaml
   • Pulls tokens from macOS Keychain where referenced
   • Skips templates for disabled services
   • Writes rendered plists to ~/Library/LaunchAgents/

3. Load the generated agents.

   # Load all Sanctum LaunchAgents
   for plist in ~/Library/LaunchAgents/com.sanctum.*.plist; do
     launchctl load "$plist"
   done

Tip

Always run with --dry-run first to verify the output before writing plists. The dry run prints each rendered plist to stdout without touching the filesystem.

Set Up the Dashboard

The dashboard is a web interface that displays the status of all services, nodes, and agents.

1. Install dependencies.

   cd ~/.sanctum/dashboard
   npm install

2. Build and start.

   Development

   npm run dev

   The dashboard will be available at http://localhost:3001.

   Production

   npm run build
   npm start

   In production, the dashboard LaunchAgent handles startup automatically. The generator creates the appropriate plist if the dashboard service is enabled in instance.yaml.

3. Verify the config endpoint.

   The dashboard serves instance configuration (with secrets excluded) at its API endpoint:

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

   You should see your instance configuration as JSON.

Set Up the VM

If you plan to run VM workloads (agent orchestration, knowledge graph), set up the Ubuntu VM.

1. Create the VM in UTM.

   Use the settings from the Requirements page. Install Ubuntu 24.04 LTS with SSH enabled.

2. Configure networking.

   The Mac needs to set the bridge IP each time the VM starts. This is handled by the UTM autostart LaunchAgent, which runs:

   sudo ifconfig bridge100 10.10.10.1/24

   A sudoers entry at /etc/sudoers.d/vmnet-bridge allows this without a password prompt.

3. Set the VM’s static IP.

   Inside the VM, configure a static IP of 10.10.10.10 on the vmnet interface using netplan or your preferred method.

4. Test connectivity.

   # From Mac
   ssh ubuntu@10.10.10.10
   
   # From VM
   ping 10.10.10.1

Caution

The VM uses Host Only networking and cannot reach the internet directly. All package installation and updates must be done through the Mac (via apt proxy, pre-downloaded packages, or rsync).

Next Steps

With the base installation complete, proceed to First Run to verify everything is working and complete initial setup.