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

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 (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, 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 (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 (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:

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):

# 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}