Machine setup

relic server setup installs the client config, shell completion, and the server as a service. On Linux it is a systemd service for your user, or with --system (as root) for the whole machine. On macOS it is a launch agent for your user. It lists every change and asks first (--yes skips the question). Running it again changes nothing.

On other systems (Windows), or without systemctl or launchctl, the command stops before changing anything; run the server by hand.

Install a user service:

relic server setup

Install a system service:

sudo relic server setup --system

To configure a package manager, use relic package setup (Package managers).

What it sets up

Each run replaces only the marked block in ~/.bashrc or ~/.zshrc. The bash block:

# relic setup completion begin
# Completion for relic, written by relic server setup.
[ -f "$HOME/.config/relic/completion.bash" ] && . "$HOME/.config/relic/completion.bash"
# relic setup completion end

The server as a service

The user service runs relic server start --worker on SQLite and the filesystem store (Single node), without root. On Linux, loginctl enable-linger keeps it running after logout and starts it at boot; setup runs it first, so it also works from a shell without a login session. The unit's PATH starts with ~/.local/bin and the directory of the relic binary, so it finds scanners installed next to relic. On macOS, it runs in your login session (macOS).

The server serves HTTPS on 127.0.0.1:8090 (--listen changes it) with a certificate authority it generates (TLS), and metrics over HTTP on 127.0.0.1:8091. relic commands on this machine trust its ca.crt (On the server's own machine).

Later runs keep the settings in server.env, so the encryption key never changes; they add missing ones. Setup restarts the service when the settings, the unit or launch agent, or the binary changed.

Before the first install, setup stops without changing anything when another program already listens on the server's address or the metrics address. After starting the service, it waits up to a minute for /readyz on the server's address to answer. It prints Done only then; otherwise it prints the answer it got and the command that shows the service's logs, and exits with status 1.

Sign in as admin with the RELIC_ADMIN_PASSWORD from server.env, and trust the authority's fingerprint when asked:

relic auth login https://127.0.0.1:8090 --user admin

Check the service:

systemctl --user status relic

Follow its logs:

journalctl --user -u relic -f

macOS

The launch agent build.relic.server starts when you log in and stops when you log out; launchd starts the server again when it exits. It runs relic server start --worker --settings ~/.config/relic/server.env, so the secrets stay in server.env and out of the launch agent. Its PATH is /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin, so it finds scanners installed with Homebrew. macOS has no system service: --system stops before changing anything.

Check the launch agent:

launchctl print gui/$(id -u)/build.relic.server

Follow its log:

tail -f ~/Library/Logs/relic.log

System service

Linux only.

sudo relic server setup --system creates:

• a relic system user with its home at /var/lib/relic
• /usr/local/bin/relic
• the settings in /etc/relic/relic.env (mode 0640, group relic)
• /etc/relic/tls for the certificate authority
• the unit /etc/systemd/system/relic.service
• bash completion in /usr/share/bash-completion/completions/relic

The service runs as relic, may write only to /var/lib/relic and /etc/relic/tls, and starts at boot. It gets no client config; relic auth login creates yours. relic server setup without --system refuses to install a user service beside it, since both would use the same ports. sudo relic server setup --system likewise refuses when the user who ran sudo has a user service; remove it first with relic server uninstall, as that user.

Check the service:

systemctl status relic

Follow its logs:

journalctl -u relic -f

Status and settings

relic server status reports the service on this machine:

╭──────────────────────────────────────────────────────────────────────────────────╮
│ This machine  user service · ~/.config/systemd/user/relic.service                │
│                                                                                  │
│ server      ● active (running)  since Sat 2026-10-03 06:30:55 +04 · pid 177655   │
│ address     https://127.0.0.1:8090  ✓ Relic v0.1.0                               │
│ metrics     http://127.0.0.1:8091/metrics                                        │
│ settings    ~/.config/relic/server.env  ✓ encryption key set                     │
│ database    sqlite ~/.local/share/relic/relic.db  1.6 MiB                        │
│ files       filesystem ~/.local/share/relic/objects  3.2 GiB in 1204 files       │
│ scanner db  ~/.local/share/relic/grype  812.4 MiB                                │
│ disk        60% free  1.1 TiB of 1.8 TiB                                         │
│ binary      ~/.local/bin/relic                                                   │
│ completion  ~/.config/relic/completion.bash                                      │
╰──────────────────────────────────────────────────────────────────────────────────╯

PostgreSQL and cloud object stores show no size. For a system service, run it with sudo. The command exits with status 1 when the service is not running or does not answer.

Print the service's settings, with secrets, keys, tokens and connection strings masked:

relic server config

Change a setting and restart the service:

relic server config set RELIC_HTTP_LISTEN_ADDRESS=0.0.0.0:8090

Change several settings with one restart:

relic server config set RELIC_SCAN_SYFT_PATH=/opt/bin/syft RELIC_SCAN_GRYPE_PATH=/opt/bin/grype

config set takes the RELIC_ and OTEL_ variables of the configuration reference. It refuses an unknown RELIC_ name, or a value the server would not start with, before changing anything. When every setting already has the value given, it writes nothing and does not restart the service.

It refuses RELIC_ADMIN_PASSWORD: that setting only sets the password of the first administrator, when the server has no users yet. Change the admin password on the Users page of the web UI, or with relic apply --force on the User resource.

Set a secret from standard input, keeping it out of the shell history and the process list:

printf '%s' "$SECRET" | relic server config set RELIC_OBJECT_STORAGE_SECRET_KEY --value-stdin

Stop

Stop the service after confirming (--yes skips the question). It starts again at the next boot, or on macOS at the next login, and the command prints how to start it now:

relic server stop

Start it again:

systemctl --user start relic.service

For a system service, use sudo and leave out --user.

On macOS, load the launch agent again:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/build.relic.server.plist

Then start it:

launchctl kickstart gui/$(id -u)/build.relic.server

Uninstall

relic server uninstall stops the service and removes its unit or launch agent, the shell completion and its rc block, and the relic binary when it is under your home directory. It asks first.

It keeps the data, server.env (which holds the encryption key the data needs), ~/.config/relic/tls, the client config, the build runs relic build recorded next to it and, on macOS, the log. --purge deletes them too, and then the Relic directories they leave empty.

Uninstall and keep the data:

relic server uninstall

Delete everything setup created, without asking:

relic server uninstall --purge --yes

Uninstall the system service, removing /usr/local/bin/relic and the bash completion:

sudo relic server uninstall --system

It keeps /etc/relic, /var/lib/relic and the relic user. With --purge, it deletes /etc/relic (with relic.env and tls), /var/lib/relic and the relic user too.