Skip to content

Installing Sanctum

Sanctum runs on a small computer in your home, and you use it from the Mac app. This guide takes a Raspberry Pi, or another Linux machine, from nothing to a home with its first light in it.

It asks for a terminal twice: the installer on the machine, and a few commands to build the Mac app, which has no download.

  • A machine that stays on. A Raspberry Pi with at least 2 GB of memory, or another 64-bit machine (ARM, Intel or AMD) running Raspberry Pi OS (64-bit), Debian or Ubuntu. An old laptop with Debian or Ubuntu Server on it works too.
  • A Zigbee USB stick that Zigbee2MQTT supports. The Nabu Casa ZBT-2 and the Dresden Elektronik ConBee III are recognised by themselves; so are other Nabu Casa and Silicon Labs sticks and other ConBee ones. Any other takes one command.
  • A Mac with Apple silicon, for the Mac app, with Git, Node.js 24 or newer and pnpm 10 to build it.
  • One home network for the machine and the Mac: the same Wi-Fi or the cable behind it, not a guest network.

A machine that already runs Debian or Ubuntu can skip this step: open a terminal on it, or one over SSH, and go on to step 2. If it has no curl, as a fresh Debian may not, install it first:

Terminal window
sudo apt-get update
sudo apt-get install -y curl ca-certificates

On a Debian set up without sudo, become root with su - and leave sudo out of the commands in this guide.

  1. On your Mac, open Raspberry Pi Imager and choose Raspberry Pi OS Lite (64-bit), listed under the other Raspberry Pi OS versions.

  2. In Imager’s settings for the system, set a hostname (say sanctum), a username and a password, your Wi-Fi if the Pi has no network cable, and turn on SSH.

  3. Write the card, put it in the Pi and plug the Pi in. Its first start takes a few minutes.

  4. From the Mac’s Terminal, connect with the username and hostname you set:

    Terminal window

Install Debian or Ubuntu Server on it from a USB stick, with the laptop on a network cable or its Wi-Fi set up in the installer. Sanctum’s installer then keeps it awake with its lid closed.

On the machine, run:

Terminal window
curl -fsSL https://raw.githubusercontent.com/meetsanctum/sanctum/main/deploy/install.sh | sudo bash

It takes a few minutes, most of them downloading, and ends with:

==> Sanctum is running
Open the Sanctum app on your Mac: it finds your home on this network.

A Raspberry Pi may then say it restarts in 10 seconds, once, to turn on a setting its system leaves off. Sanctum comes back by itself.

Running the command again is safe: it leaves a running Sanctum alone and finishes an install that was cut short. What the installer changes lists everything it touches.

Plug the stick into the machine. Zigbee starts by itself within a minute, before or after the next steps. Plug in one stick only: with several, Sanctum waits for you to unplug the ones it shouldn’t use.

On the Mac:

Terminal window
git clone https://github.com/meetsanctum/sanctum.git
cd sanctum
git checkout "$(git describe --tags --abbrev=0 origin/main)"
pnpm install
pnpm --filter @meetsanctum/desktop package
open apps/desktop/release

The third line takes the code of the newest release, matching a new install on the stable channel. For the edge channel, use the commit described under Updating instead. The last opens the folder with the disk image, Sanctum-<version>-arm64.dmg: open it and drag Sanctum into Applications.

Built on your own Mac, the app opens without a warning. On a Mac it was copied to, macOS holds it back the first time: System Settings → Privacy & Security → Open Anyway lets it start.

When macOS asks whether Sanctum may find devices on your local network, allow it. That is how the app finds your home.

  1. Open Sanctum. Under Choose your home it lists New home, ready to set up, with the machine’s address. Choose Set up.
  2. Enter your name, a colour, a username and a password, and choose Set up. You are the first person in the home.
  3. The dashboard opens on Set up your home, three steps in any order:
    • Set where the home is, for the weather and for lights that follow daylight.
    • Add your rooms, so each device is named after the room it is in.
    • Add lights, switches and remotes. Choose Add devices, then switch a new device on or reset it, as its instructions say. New devices can join for about four minutes; each shows up as it joins, to name and put in a room.

Set your home up soon after installing. Until someone has, anyone on your network who opens the app can.

On another Mac, the app lists your home with Sign in. A person signs in with their own username and password; a Mac the household shares chooses This is a shared device and is approved from a device that is already in.