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.
What you need
Section titled “What you need”- 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.
1. Prepare the machine
Section titled “1. Prepare the machine”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:
sudo apt-get updatesudo apt-get install -y curl ca-certificatesOn a Debian set up without sudo, become root with su - and leave sudo
out of the commands in this guide.
A Raspberry Pi with a blank card
Section titled “A Raspberry Pi with a blank card”-
On your Mac, open Raspberry Pi Imager and choose Raspberry Pi OS Lite (64-bit), listed under the other Raspberry Pi OS versions.
-
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. -
Write the card, put it in the Pi and plug the Pi in. Its first start takes a few minutes.
-
From the Mac’s Terminal, connect with the username and hostname you set:
Terminal window
An old laptop
Section titled “An old laptop”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.
2. Install Sanctum
Section titled “2. Install Sanctum”On the machine, run:
curl -fsSL https://raw.githubusercontent.com/meetsanctum/sanctum/main/deploy/install.sh | sudo bashIt takes a few minutes, most of them downloading, and ends with:
==> Sanctum is runningOpen 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.
3. Plug in the Zigbee stick
Section titled “3. Plug in the Zigbee stick”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.
4. Build the Mac app
Section titled “4. Build the Mac app”On the Mac:
git clone https://github.com/meetsanctum/sanctum.gitcd sanctumgit checkout "$(git describe --tags --abbrev=0 origin/main)"pnpm installpnpm --filter @meetsanctum/desktop packageopen apps/desktop/releaseThe 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.
5. Set up your home
Section titled “5. Set up your home”- Open Sanctum. Under Choose your home it lists New home, ready to set up, with the machine’s address. Choose Set up.
- Enter your name, a colour, a username and a password, and choose Set up. You are the first person in the home.
- 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.