Install

Get Sanctuary running.

Sanctuary runs entirely in Docker. Any reasonably modern Linux, macOS, or Windows (with WSL2) machine works. First install takes 2–5 minutes; restarts are near-instant.

Experimental software in active development — start small while you get comfortable. See the full disclaimer.

Prerequisites

› Docker (Desktop, Engine, Colima, or Podman all work)
› git
› A modern browser: Chrome, Edge, or Brave for hardware-wallet features (WebUSB/WebHID/WebSerial)

Quickest path

One command. The script clones the repo, generates secrets and self-signed SSL certs, builds the containers, and starts the stack.

$ curl -fsSL https://codeberg.org/nekoguntai-castle/sanctuary/raw/branch/main/install.sh | bash

Always read a script before piping it to a shell. The source is published in the repository.

Prefer to choose the directory?

$ git clone https://codeberg.org/nekoguntai-castle/sanctuary.git
$ cd sanctuary
$ ./install.sh

When it finishes, open https://localhost:8443 and accept the self-signed certificate warning.

Linux

Docker Engine is the recommended path. Podman works for rootless setups.

# Ubuntu / Debian
$ curl -fsSL https://get.docker.com | sh
$ sudo usermod -aG docker $USER
# log out and back in so the group change takes effect

$ git clone https://codeberg.org/nekoguntai-castle/sanctuary.git
$ cd sanctuary
$ ./scripts/setup.sh

# Fedora
$ sudo dnf install docker docker-compose-plugin
$ sudo systemctl enable --now docker
$ sudo usermod -aG docker $USER

# Arch Linux
$ sudo pacman -S docker docker-compose
$ sudo systemctl enable --now docker
$ sudo usermod -aG docker $USER

Podman (rootless):

$ sudo apt install podman podman-compose   # or: sudo dnf install podman podman-compose
$ git clone https://codeberg.org/nekoguntai-castle/sanctuary.git && cd sanctuary
$ ./scripts/setup.sh --no-start
$ podman-compose up -d

macOS

Option 1: Docker Desktop — download from docker.com (Apple Silicon or Intel), drag to Applications, then:

$ git clone https://codeberg.org/nekoguntai-castle/sanctuary.git
$ cd sanctuary
$ ./scripts/setup.sh

Option 2: Colima — lightweight alternative via Homebrew:

$ brew install colima docker docker-compose
$ colima start
$ git clone https://codeberg.org/nekoguntai-castle/sanctuary.git && cd sanctuary
$ ./scripts/setup.sh

Windows

Option 1: Docker Desktop + WSL2 (recommended)

Install Docker Desktop; accept its WSL2 prompts.
From PowerShell:

> git clone https://codeberg.org/nekoguntai-castle/sanctuary.git
> cd sanctuary
> wsl ./scripts/setup.sh

Option 2: WSL2 + Docker (no Docker Desktop)

> wsl --install -d Ubuntu   # in PowerShell; reboot after

# Then open Ubuntu from Start menu and run:
$ curl -fsSL https://get.docker.com | sh
$ sudo usermod -aG docker $USER
# close & reopen Ubuntu terminal

$ git clone https://codeberg.org/nekoguntai-castle/sanctuary.git && cd sanctuary
$ ./scripts/setup.sh

Note: After the wsl --install reboot, run everything in the Ubuntu (Linux) terminal — not PowerShell or Command Prompt.

Umbrel

If you run an Umbrel node, Sanctuary is available as a Community App and auto-connects to your Electrum server.

Open the App Store in your Umbrel.
Click the ⋯ menu in the upper-right corner.
Select Community App Stores.
Paste: https://codeberg.org/nekoguntai-castle/sanctuary-umbrel
Click Add.
Find Sanctuary in the App Store and click Install.

Umbrel limitation: Umbrel serves apps over HTTP, not HTTPS. WebUSB hardware wallets (Ledger, Trezor) and QR camera scanning both require HTTPS, so they won't work here. Air-gapped workflows (import descriptors/JSON, create and import PSBTs via MicroSD or file) work fine. For USB wallets and camera scanning, use the quick-install method above on a machine where you can serve HTTPS.

Manual Docker Compose

If you want full control of secrets, ports, and environment, run it yourself.

$ git clone https://codeberg.org/nekoguntai-castle/sanctuary.git
$ cd sanctuary
$ ./scripts/setup.sh       # generates .env, SSL certs, builds, and starts

The setup script generates secure random values for JWT_SECRET, ENCRYPTION_KEY, ENCRYPTION_SALT, GATEWAY_SECRET, and POSTGRES_PASSWORD, plus self-signed SSL certificates for HTTPS.

First run

Open the app. Navigate to https://localhost:8443 in Chrome, Edge, or Brave. Accept the self-signed certificate warning (Advanced → Proceed).
Log in. Default credentials: admin / sanctuary.
Change the password. Required on first login. Minimum 8 characters; use a real password manager.
Add a wallet. Connect a hardware device (Ledger, Trezor, BitBox02, Jade) or import via QR / JSON / output descriptor.

Day-to-day commands

$ ./start.sh                  # start
$ ./start.sh --stop           # stop
$ ./start.sh --logs           # tail logs
$ ./start.sh --with-tor       # route through Tor
$ ./start.sh --with-ai        # start bundled local AI
$ ./start.sh --with-monitoring # Grafana / Prometheus / Jaeger

Upgrading

Re-run the installer. It fetches the latest release tag and rebuilds.

$ cd ~/sanctuary
$ ./install.sh

Do not use git pull to upgrade — the installer checks out a release tag, which puts Git in detached-HEAD state. Re-running ./install.sh is the supported path.

Troubleshooting

Stuck on a port conflict, hardware wallet not showing up, certificate error? The troubleshooting section of the README covers the common cases. Anything else, open an issue.