Run with systemd

Use systemd when you want the Sigvane CLI to keep polling after you log out or after the server restarts.

This page assumes you already finished CLI getting started and have a working config.

1. Install The CLI

Install the sigvane binary somewhere the service can run it, such as:

/usr/local/bin/sigvane

Check it:

/usr/local/bin/sigvane version

2. Create A Service User

Create a dedicated Linux user for the worker:

sudo useradd --system --home /var/lib/sigvane --shell /usr/sbin/nologin sigvane
sudo install -d -o sigvane -g sigvane -m 0750 /var/lib/sigvane
sudo install -d -o root -g root -m 0750 /etc/sigvane

3. Create The Config

Put the CLI config at:

/etc/sigvane/config.yaml

Example:

version: 1

server:
  url: https://api.sigvane.com
  api_key: ${SIGVANE_API_KEY}
  poll_interval: 5s
  shutdown_grace_period: 30s

handlers:
  - inbox: github-repo
    command: ["/usr/local/bin/process-github-webhook"]
    stdin: full_item

Use your inbox slug and handler command.

For a service, prefer absolute paths in command. The service does not run in your interactive shell, so it may not have the same working directory or PATH.

Set file permissions:

sudo chown root:sigvane /etc/sigvane/config.yaml
sudo chmod 0640 /etc/sigvane/config.yaml

4. Add The API Key

Create an environment file:

/etc/sigvane/sigvane.env

Add:

SIGVANE_API_KEY=replace-me

Then restrict it:

sudo chown root:root /etc/sigvane/sigvane.env
sudo chmod 0600 /etc/sigvane/sigvane.env

For stronger secret handling, use your platform’s secret manager or systemd credentials instead of a plain environment file.

5. Check The Config

In your current shell, set the API key:

export SIGVANE_API_KEY='replace-me'

Then run the config check as the service user:

sudo -u sigvane env SIGVANE_API_KEY="$SIGVANE_API_KEY" \
  /usr/local/bin/sigvane config check --path /etc/sigvane/config.yaml

This checks that the config is valid and that ${SIGVANE_API_KEY} resolves. The service itself reads the API key from /etc/sigvane/sigvane.env.

6. Create The Service

Create:

/etc/systemd/system/sigvane.service

Use this service file:

[Unit]
Description=Sigvane CLI worker
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sigvane
Group=sigvane
EnvironmentFile=/etc/sigvane/sigvane.env
ExecStart=/usr/local/bin/sigvane inbox poll --config /etc/sigvane/config.yaml --state /var/lib/sigvane/state.json
Restart=on-failure
RestartSec=5s
TimeoutStopSec=45s

[Install]
WantedBy=multi-user.target

The explicit --state path keeps the worker cursor in /var/lib/sigvane/state.json.

7. Start The Service

Reload systemd and start the worker:

sudo systemctl daemon-reload
sudo systemctl enable --now sigvane

Check status:

sudo systemctl status sigvane

Watch logs:

sudo journalctl -u sigvane -f

Update The Config

After changing /etc/sigvane/config.yaml, check it and restart the service:

sudo -u sigvane env SIGVANE_API_KEY="$SIGVANE_API_KEY" \
  /usr/local/bin/sigvane config check --path /etc/sigvane/config.yaml

sudo systemctl restart sigvane

Stop The Service

sudo systemctl stop sigvane

When stopped, the CLI receives SIGTERM and gives the current handler time to finish.

Handler Safety

The CLI only advances its saved cursor after a handler exits successfully. If the service stops or the handler fails before that, the same inbox item may be read again after restart.

Make handlers safe to run more than once for the same providerDeliveryId.

See CLI operations for more detail about state files and replay behavior.