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

> Effortlessly set up the PostgreSQL auto-push daemon as a systemd service for AgentsView. Learn how the pg service install command simplifies daemon management and ensures automatic startup.

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

---

**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`](https://github.com/kenn-io/agentsview/blob/main/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:

```bash
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:

```bash
chmod 600 ~/.agentsview/config.toml

```

The configuration loader in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg.go), the `service install` logic builds a user-level systemd unit and executes the appropriate `systemctl` commands.

Run the installation:

```bash
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:

```bash
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:

```bash
agentsview pg service status

```

Stream logs in real time:

```bash
agentsview pg service logs -f

```

Stop and remove the service permanently:

```bash
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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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.