Skip to content

Run as a service

The one-command installer and the Debian package set up the service for you. This page lists the commands for each, and how to set up the service by hand for a release archive.

Installer, Linux Installer, macOS Debian package
Service systemd user unit prism launchd agent com.prism.router system unit prism
Status systemctl --user status prism launchctl print gui/$(id -u)/com.prism.router systemctl status prism
Stop systemctl --user stop prism launchctl bootout gui/$(id -u)/com.prism.router sudo systemctl stop prism
Start systemctl --user start prism launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.prism.router.plist sudo systemctl start prism
Restart after editing the config or keys systemctl --user restart prism launchctl kickstart -k gui/$(id -u)/com.prism.router sudo systemctl restart prism
Logs journalctl --user -u prism -f ~/Library/Logs/prism/prism.out.log, prism.err.log journalctl -u prism -f
Config ~/.prism/config.toml ~/.prism/config.toml /etc/prism/config.toml
Keys ~/.config/prism/prism.env ~/.config/prism/prism.env /etc/prism/prism.env

Prism reads its configuration once at start. A change in config.toml or in the key file takes effect after a restart. Settings saved in the web console also apply after a restart; the console can restart Prism itself when Allow restart and stop from the console is on (Configuration → Maintenance).

A systemd user unit runs only while you are logged in. On a machine that must serve requests all the time, allow your user services to run without a login session, once:

Terminal window
loginctl enable-linger "$USER"

Prism uses its exit code to tell the supervisor what to do:

Exit code Meaning Supervisor should
75 restart requested (console restart, installed update) start Prism again
0 stop requested (console stop) leave it stopped
1 failure (for example an invalid config) start it again after a delay

The units the installer and the Debian package install follow these rules:

[Unit]
StartLimitIntervalSec=0
[Service]
Restart=always
RestartSec=5
RestartForceExitStatus=75
RestartPreventExitStatus=0

Restart=always with RestartSec=5 and StartLimitIntervalSec=0 restarts a crashed Prism every 5 seconds without giving up. StartLimit* keys work only in the [Unit] section; systemd ignores them in [Service]. Without RestartPreventExitStatus=0, a stop from the console is undone 5 seconds later. The launchd agent restarts Prism when it exits with a non-zero code (KeepAlive.SuccessfulExit = false, at most once every 5 seconds).

An invalid config makes Prism exit with serve failed: … on stderr. Under systemd that line is in the journal, and the service is restarted every 5 seconds until the config is fixed. Versions → Check configuration in the console checks the saved config inside the running service. From a terminal:

Terminal window
prism config check ~/.prism/config.toml

A variable the config names but the terminal does not have (the service reads it from its environment file) is reported as not set in this shell and does not fail the check; add --strict to make it an error.

Each release archive carries the reference units in support/systemd/prism.service and support/launchd/com.prism.router.plist.

Terminal window
sudo useradd --system --home-dir /var/lib/prism --shell /usr/sbin/nologin prism
sudo install -d -o prism -g prism /var/lib/prism
sudo install -d -m 0755 /etc/prism
sudo install -m 0755 prism /usr/local/bin/prism
sudo touch /var/lib/prism/config.toml && sudo chown prism:prism /var/lib/prism/config.toml
sudo install -m 0600 /dev/null /etc/prism/prism.env # provider keys, one VAR=value per line
sudo cp support/systemd/prism.service /etc/systemd/system/prism.service
sudo systemctl daemon-reload
sudo systemctl enable --now prism

The unit runs /usr/local/bin/prism serve as user prism in /var/lib/prism, so the config is /var/lib/prism/config.toml and state goes to /var/lib/prism/data. It reads keys from /etc/prism/prism.env.

A provider whose api_key_env names a variable that is not set (and that has no key stored in the console) is disabled with one log line: provider "<name>" disabled: api_key_env <VAR> is not set.

The agent runs as your user, so keys stored in your login keychain with prism setup are readable.

Terminal window
mkdir -p ~/.prism ~/Library/Logs/prism ~/.config/prism
touch ~/.prism/config.toml
install -m 0600 /dev/null ~/.config/prism/prism.env
cp support/launchd/com.prism.router.plist ~/Library/LaunchAgents/
sed -i '' "s/YOUR_USER/$(whoami)/g" ~/Library/LaunchAgents/com.prism.router.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.prism.router.plist

The agent loads ~/.config/prism/prism.env, then runs /usr/local/bin/prism serve in ~/.prism. Install the binary there, or edit the path in the plist.

Terminal window
curl -fsS http://127.0.0.1:18000/health # {"status":"ok"}

/prism/status returns a full status snapshot. When PRISM_ADMIN_TOKEN or PRISM_READ_TOKEN is set, it needs that token in X-Prism-Admin-Token (or the read token in X-Prism-Read-Token).