DevLens – Binary + Systemd Setup

This guide shows how to install the three DevLens components (app, agent, AI) from the binary releases and run each as a systemd service on a single host. This guide assumes you have the following:

  1. A Linux distribution with systemd (Ubuntu, Debian, CentOS, RHEL, etc.) See the release page: https://source.rdctd.de/devlens/releases for supported distributions.
  2. curl or wget for downloading files
  3. tar for extracting archives (and gzip for decompression)

1. Prepare the host

Create a dedicated user to run the service (optional, but recommended for security):

sudo useradd -r -s /usr/sbin/nologin devlens

Create the application directory, where the DevLens binaries will exist:

sudo mkdir -p /opt/devlens
sudo chown devlens:devlens /opt/devlens

Create a data directory (where the DB, logs and retention data live) should be writable by that user.

sudo mkdir -p /var/lib/devlens
sudo chown devlens:devlens /var/lib/devlens

!!! tip The data directory should be backed up!

2. Download and install the binaries

Step 1 – Grab the latest release Replace <VERSION> with the tag you want to use (1.2.3, latest, …).

VERSION=latest
curl -L "https://source.rdctd.de/devlens/releases/devlens-${VERSION}.tar.gz" | \
    tar -xz -C /opt/devlens

The archive contains:

/opt/devlens/
├─ app
├─ agent
├─ ai
└─ README.md

Make sure each binary is executable:

sudo chmod 755 /opt/devlens/{app,agent,ai}

3. Write systemd unit files

Most modern Linux distributions use systemd to manage services (Debian, Ubuntu, Arch, CentOS, RHEL, etc.). For each component, create a systemd service file to ensure safe restarts.

Create the systemd unit files under /etc/systemd/system/:

3.1 devlens-app.service

[Unit]
Description=DevLens App – UI & alert dispatcher
After=network.target

[Service]
User=devlens
Group=devlens
WorkingDirectory=/opt/devlens
ExecStart=/opt/devlens/app -config=/var/lib/devlens/devlens.toml
Restart=on-failure

[Install]
WantedBy=multi-user.target

3.2 devlens-agent.service

[Unit]
Description=DevLens Agent – host telemetry collector
After=network.target

[Service]
User=devlens
Group=devlens
WorkingDirectory=/opt/devlens
ExecStart=/opt/devlens/agent -config=/var/lib/devlens/devlens.toml
Restart=on-failure

[Install]
WantedBy=multi-user.target

4.3 devlens-ai.service

[Unit]
Description=DevLens AI – LLM-based fix suggestions
After=network.target

[Service]
User=devlens
Group=devlens
WorkingDirectory=/opt/devlens
ExecStart=/opt/devlens/ai -config=/var/lib/devlens/devlens.toml
Restart=on-failure

[Install]
WantedBy=multi-user.target

4. Enable and start the services

Reload the configuration to detect your new unit files, then enable and launch them:

sudo systemctl daemon-reload

sudo systemctl enable --now devlens-app
sudo systemctl enable --now devlens-agent
sudo systemctl enable --now devlens-ai

Verify everything is running:

systemctl status devlens-{app,agent,ai}

You should see each service in the active (running) state.

Open a browser to http://<host-ip>:8000 – the DevLens UI should be live.

5. Updating to a new version

  1. Download & replace the binaries (step 2, but use the new <VERSION>).

  2. Restart the services: sudo systemctl restart devlens-{app,agent,ai}

  3. Check logs to ensure the restart was successful: journalctl -u devlens-app -f

7. Cleaning up

To remove the services and data:

sudo systemctl disable --now devlens-{app,agent,ai}
sudo rm /etc/systemd/system/devlens-*.service
sudo systemctl daemon-reload

# Optional: delete binaries and data
sudo rm -rf /opt/devlens
sudo rm -rf /var/lib/devlens