How to Set Up the PostgreSQL Auto-Push Daemon as a systemd Service for AgentsView

The AgentsView CLI includes a pg service install command that generates a user-level systemd unit file, enables the service, and starts the PostgreSQL auto-push daemon automatically.

AgentsView can continuously sync locally stored sessions to a shared PostgreSQL database without manual intervention using a background daemon. This guide explains how to configure and deploy the PostgreSQL auto-push daemon as a systemd service using the built-in CLI tooling. According to the kenn-io/agentsview source code, the service uses the same Sync.Push method found in internal/postgres/push.go that powers the interactive agentsview pg push --watch command.

Configure PostgreSQL Access

Before installing the service, store your database credentials in the AgentsView configuration file. The daemon reads this file at startup to establish the PostgreSQL connection.

Create the configuration directory and file:

mkdir -p ~/.agentsview
cat > ~/.agentsview/config.toml <<EOF
[pg]
dsn = "postgres://user:pass@db.example.com/agentsview?sslmode=disable"
EOF

Secure the file since it contains credentials:

chmod 600 ~/.agentsview/config.toml

The configuration loader in internal/config/config.go parses this TOML file and exposes the [pg] section to the daemon.

Install the systemd Service

The CLI provides a dedicated subcommand to handle unit file creation and service registration. In cmd/agentsview/pg.go, the service install logic builds a user-level systemd unit and executes the appropriate systemctl commands.

Run the installation:

agentsview pg service install

This command performs three actions:

1. Generates $HOME/.config/systemd/user/agentsview-pg.service
2. Runs systemctl --user enable agentsview-pg.service
3. Runs systemctl --user start agentsview-pg.service

The CLI prints the exact systemctl commands executed for verification.

Enable Persistent Operation on Headless Servers

By default, user-level systemd services terminate when the user logs out. For headless servers or automated environments, enable linger to keep the service running after logout:

loginctl enable-linger "$USER"

The install command detects headless environments and suggests this command automatically, as documented in the README section on automatic push services.

Manage the Service

After installation, use the CLI to inspect and control the daemon without manually invoking systemctl.

Check service status:

agentsview pg service status

Stream logs in real time:

agentsview pg service logs -f

Stop and remove the service permanently:

agentsview pg service uninstall

This removes the unit file from $HOME/.config/systemd/user/ and disables the service.

Daemon Implementation Details

The background daemon invokes the Sync.Push method defined in internal/postgres/push.go (lines 47-55). This method:

• Normalizes session timestamps
• Determines the last-push watermark
• Streams only new or changed sessions to PostgreSQL

The daemon effectively runs the equivalent of agentsview pg push --watch as a long-lived process, watching session directories and periodically pushing data using the DSN from ~/.agentsview/config.toml.

Summary

• Store credentials in ~/.agentsview/config.toml with restricted permissions (chmod 600)
• Install the service using agentsview pg service install, which creates a user-level unit at $HOME/.config/systemd/user/agentsview-pg.service
• Enable linger with loginctl enable-linger "$USER" on headless servers to survive logouts
• Manage lifecycle through agentsview pg service status, logs, and uninstall commands
• Core logic resides in internal/postgres/push.go using the Sync.Push method for incremental synchronization

Frequently Asked Questions

How does the auto-push daemon handle authentication?

The daemon reads the PostgreSQL DSN from the [pg] section of ~/.agentsview/config.toml at startup. The file must be readable by the user running the service and should have permissions set to 600 to protect credentials. No authentication data is hardcoded in the systemd unit file.

What happens if the PostgreSQL server becomes unavailable?

The daemon runs continuously as a systemd service and will retry connections based on the implementation in internal/postgres/push.go. Check agentsview pg service logs -f to view connection errors and retry attempts. The service remains active and attempts to reconnect automatically when the database becomes available again.

Can I run the daemon as a system-wide service instead of a user service?

The current CLI implementation in cmd/agentsview/pg.go generates user-level units (--user) stored in $HOME/.config/systemd/user/. To run system-wide, you would need to manually create a system unit file in /etc/systemd/system/ and run systemctl without the --user flag, ensuring the configuration file is accessible to the system user.

How do I verify that sessions are actually syncing?

Use agentsview pg service status to confirm the service is active, then run agentsview pg service logs -f to view real-time push activity. The logs indicate when the Sync.Push method detects new sessions and streams them to PostgreSQL. You can also query your PostgreSQL database directly to verify that new session records appear.

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