# How to Run Agentsview as a systemd or launchd Service: Complete Setup Guide

> Effortlessly run Agentsview as a systemd or launchd service. Use the simple install command to automatically set up and start the service on your OS. Get complete guide here.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-06-12

---

**Use the `agentsview pg service install` command to automatically generate, enable, and start the appropriate service unit for your operating system.**

Agentsview ships with a built-in **pg-push background service** that continuously syncs session data to PostgreSQL. According to the kenn-io/agentsview source code, you can run this process as a native OS daemon using a single CLI command that generates platform-specific configuration files. This guide explains how to run agentsview as a systemd or launchd service on Linux and macOS, covering the underlying implementation and headless server considerations.

## Installing the Background Service

The `agentsview pg service install` command handles the entire lifecycle of creating and starting the service. This command is defined in **[`cmd/agentsview/pg_service.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_service.go)** (lines 17-33), which delegates to the service manager implementation.

Crucially, the command validates all paths and arguments before writing any system files. In [`cmd/agentsview/pg_service_manager.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_service_manager.go), the **`buildServiceSpec`** function (lines 11-44) constructs a specification containing the binary path, data directory, and log file location. The **`validateServiceSpec`** function (lines 76-100) then checks for unsafe characters that could break unit file syntax, ensuring the generated service definition is safe to execute.

### Platform Detection and Unit Generation

The **`newServiceManager()`** function in [`pg_service_manager.go`](https://github.com/kenn-io/agentsview/blob/main/pg_service_manager.go) (lines 176-199) automatically detects the host operating system and instantiates the correct manager implementation—systemd for Linux or launchd for macOS. Each manager's `install()` method writes the appropriate unit file to the standard location, enables the service using `systemctl --user enable` or `launchctl bootstrap`, and immediately starts the process.

## Linux systemd Configuration

On Linux, agentsview runs as a **user-level systemd service** rather than a system-wide daemon. This approach avoids requiring root privileges while still allowing the service to persist across reboots when properly configured.

### Enabling Lingering for Headless Servers

If you are running agentsview on a headless Linux box, the service will stop when you log out unless **user lingering** is enabled. The `systemdManager` implementation in [`pg_service_manager.go`](https://github.com/kenn-io/agentsview/blob/main/pg_service_manager.go) (lines 71-75) checks the linger status and prints a warning if it is disabled.

To enable lingering and allow the service to survive logout and boot automatically, run:

```bash
loginctl enable-linger "$USER"

```

This command may require sudo privileges depending on your system configuration.

## macOS launchd Configuration

On macOS, the service manager creates a `*.plist` file in `~/Library/LaunchAgents` and loads it using `launchctl bootstrap`. This integrates agentsview with macOS's native service management framework, allowing the pg-push process to start automatically upon user login and restart if it crashes.

## Managing the Service Lifecycle

Once installed, control the service using the following commands as documented in the README (lines 361-368):

```bash

# Check if the service is active and see recent log entries

agentsview pg service status

# Follow the log output in real-time (equivalent to tail -f)

agentsview pg service logs -f

# Stop the service and remove the unit file

agentsview pg service uninstall

```

For headless Linux setups, the README (lines 371-374) also documents the lingering warning that appears after installation, reminding you to run `loginctl enable-linger "$USER"` if the service needs to persist beyond the current session.

## Summary

- The `agentsview pg service install` command in [`cmd/agentsview/pg_service.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_service.go) (lines 17-33) automates service creation for both Linux and macOS.
- The implementation validates file paths and escapes unsafe characters via `validateServiceSpec` (lines 76-100) before generating unit files.
- Linux uses systemd user services with automatic detection of lingering requirements; macOS uses launchd agents in `~/Library/LaunchAgents`.
- Enable lingering on headless Linux systems using `loginctl enable-linger "$USER"` to prevent the service from stopping at logout.
- Manage the running service with `status`, `logs`, and `uninstall` subcommands.

## Frequently Asked Questions

### Do I need root privileges to run agentsview as a service?

No. The service runs under your user account using systemd's user-level services or launchd's user agents. However, enabling lingering on Linux using `loginctl enable-linger` may require administrator privileges if not already configured by your system administrator.

### Why does my service stop when I log out on Linux?

Systemd user services terminate when the last user session closes unless lingering is enabled. The agentsview CLI detects this condition via the `lingerChecker` interface and warns you after installation. Run `loginctl enable-linger "$USER"` to keep the service running after logout and across reboots.

### Where are the service files stored?

On Linux, the systemd unit file is written to the standard user location, typically `~/.config/systemd/user/`. On macOS, the launchd plist file is placed in `~/Library/LaunchAgents`. Both locations follow platform conventions and do not require modifying system directories.

### Can I customize the service configuration after installation?

Yes. You can edit the generated unit file directly using standard systemd or launchd tools. However, note that running `agentsview pg service uninstall` will remove the file entirely. For persistent customizations, consider modifying the `serviceSpec` generation logic or manually creating a unit file based on the template generated by `buildServiceSpec`.