Install on Linux

This page installs Mandala on a Linux machine as one systemd service, with its data in ~/.mandala. It takes about 30 minutes, most of it compiling.

Mandala is distributed as source today. Packaged downloads and a one-line installer are Coming soon.

Before you start

• A 64-bit Linux machine (Debian 12, Ubuntu 22.04 or newer work well) with at least 4 GB of RAM and 20 GB free. Compiling needs more memory than running: 8 GB or more is comfortable. See System requirements.
• A user account that will own Mandala's data (the examples use sam).
• Tailscale installed and logged in on this machine and on the devices you will use.
• Build tools: git, curl, a C and C++ compiler with C++20 support (build-essential or clang), pkg-config, libssl-dev.
• rustup. The repository pins the Rust toolchain (rust-toolchain.toml, Rust 1.98.0); rustup installs it on the first build.
• Node.js 20 or newer with npm, to build the web app.

1. Build

git clone <the Mandala repository> mandala && cd mandala
cargo build --release -p mandala
(cd applications/workspace && npm ci && npm run build)

The binary is target/release/mandala; the web app is applications/workspace/dist.

2. Install the files

mkdir -p ~/.mandala/bin ~/.mandala/goethe/me/{docs,types,views} ~/.mandala/goethe/companion/{docs,types,views}
chmod 700 ~/.mandala ~/.mandala/goethe ~/.mandala/goethe/me ~/.mandala/goethe/companion
install -m 755 target/release/mandala ~/.mandala/bin/mandala
cp -r applications/workspace/dist ~/.mandala/web

Vault directories must be private to Mandala's user (mode 700), or Mandala refuses to open them. goethe/me becomes your own vault (what you see in Knowledge); goethe/companion is your accomplice's private vault (its goals, initiatives and diary).

3. Write the configuration

Create ~/.mandala/mandala.env and keep it private (chmod 600):

# Where Mandala keeps its data and serves the app from
ALMA_DATA_DIR=/home/sam/.mandala
ALMA_WEB_ROOT=/home/sam/.mandala/web
ALMA_LISTEN=127.0.0.1:8787

# Your time zone (routines run in it)
ALMA_TIMEZONE=Europe/Paris

# Your vault and your accomplice's vault
ALMA_GOETHE_JULIEN_ROOT=/home/sam/.mandala/goethe/me
ALMA_GOETHE_AGENT_ROOTS='{"alma":"/home/sam/.mandala/goethe/companion"}'

• Do not set ALMA_OWNER_NAME or MANDALA_PRINCIPAL on a new home: leaving them out is what makes Mandala show the first-run assistant, where you give your first name and Face ID.
• Keep the single quotes around the JSON value of ALMA_GOETHE_AGENT_ROOTS.
• ALMA_GOETHE_JULIEN_ROOT is the variable for your vault, whatever your name; it keeps its historical name.
• The key in ALMA_GOETHE_AGENT_ROOTS must be your accomplice's agent id (ALMA_AGENT_ID, alma unless you set another).
• Without ALMA_DATA_DIR, Mandala uses ~/.alma. Set it.

Every variable is described in Environment variables.

4. Run it as a service

Create /etc/systemd/system/mandala.service:

[Unit]
Description=Mandala
After=network-online.target
Wants=network-online.target

[Service]
User=sam
Group=sam
EnvironmentFile=/home/sam/.mandala/mandala.env
ExecStart=/home/sam/.mandala/bin/mandala serve
Restart=always
RestartSec=2
TimeoutStopSec=30
NoNewPrivileges=yes
PrivateTmp=yes

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable --now mandala.service
curl -s http://127.0.0.1:8787/health

Restart=always matters: Mandala restarts itself to load a new vault or contract, and a clean exit must bring it back.

5. Open it from your devices

Mandala listens on the loopback address only. Publish it on your tailnet with HTTPS:

sudo tailscale serve --bg --https=443 http://127.0.0.1:8787

Open https://<machine>.<tailnet>.ts.net from any device on your tailnet. HTTPS is required for Face ID and passkeys, notifications and the installable app. Keep this name: passkeys are bound to it. See Tailscale and HTTPS.

6. Continue

• The first run — create your identity with your first name and Face ID, and choose a model.

Optional pieces