# How to Deploy kenn-io/agentsview: Complete Deployment Options Guide

> Explore kenn-io/agentsview deployment options. Choose from single binary to containerized PostgreSQL for local dev or production team dashboards. Get your complete guide.

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

---

**The kenn-io/agentsview project supports eight distinct deployment modes ranging from a single binary executable to containerized PostgreSQL-backed services, enabling everything from local development to production team dashboards.**

The kenn-io/agentsview repository provides a flexible agent session visualization platform built in Go with an embedded Svelte UI. Understanding the available deployment options for kenn-io/agentsview allows you to choose the right architecture—whether you need a standalone desktop application, a Dockerized microservice, or a scalable PostgreSQL-backed team server.

## Local Binary Deployment

The simplest deployment method uses a single Go executable that embeds the Svelte frontend and serves the UI on `127.0.0.1:8080` by default. In [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go), the CLI entry point initializes a SQLite archive (with FTS5 enabled) stored in `~/.agentsview` by default, watches local agent session directories, and synchronizes them into the database.

To run locally without containers:

```bash

# Build or download the binary

./agentsview serve

```

The server binds to the loopback address and validates the `Host` header to prevent DNS-rebinding attacks. Use `--public-url` and `--require-auth` when exposing beyond localhost.

## Docker Container Deployment

For portable, reproducible environments without the Go toolchain, use the official container image hosted at `ghcr.io/kenn-io/agentsview:latest`. The `Dockerfile` defines a multi-stage build that runs `agentsview serve` by default, expecting data volumes and agent directory mounts.

```bash
docker run --rm -p 127.0.0.1:8080:8080 \
  -v agentsview-data:/data \
  -v "$HOME/.claude/projects:/agents/claude:ro" \
  -v "$HOME/.forge:/agents/forge:ro" \
  -e CLAUDE_PROJECTS_DIR=/agents/claude \
  -e FORGE_DIR=/agents/forge \
  ghcr.io/kenn-io/agentsview:latest

```

This configuration mounts `agentsview-data` to persist the SQLite archive and read-only volumes for agent session directories that agentsview indexes.

## Production Docker Compose Setup

For production-grade multi-container deployments, reference the [`docker-compose.prod.yaml`](https://github.com/kenn-io/agentsview/blob/main/docker-compose.prod.yaml) file. This configuration persists the data volume and can be integrated with reverse proxies like Traefik or Nginx.

```yaml

# docker-compose.prod.yaml structure

services:
  agentsview:
    image: ghcr.io/kenn-io/agentsview:latest
    volumes:
      - agentsview-data:/data
      - /path/to/agent/sessions:/agents:ro
    environment:
      - AGENTSVIEW_REQUIRE_AUTH=true
    ports:
      - "127.0.0.1:8080:8080"

```

The production compose file handles data persistence and environment variable injection, using the same configuration schema as the binary.

## PostgreSQL Backend Deployment

To enable team-wide dashboards, mirror the local SQLite data to PostgreSQL using `agentsview pg push`, then serve a read-only UI directly from the database with `agentsview pg serve`. The implementation in [`internal/postgres/push.go`](https://github.com/kenn-io/agentsview/blob/main/internal/postgres/push.go) upserts rows into the `sessions` and `messages` tables defined in [`internal/postgres/schema.go`](https://github.com/kenn-io/agentsview/blob/main/internal/postgres/schema.go).

```bash

# Push local SQLite to PostgreSQL

agentsview pg push \
  -e AGENTSVIEW_PG_URL='postgres://user:pass@postgres.example.com:5432/agentsview?sslmode=require'

# Serve UI from PostgreSQL

agentsview pg serve

```

This mode treats PostgreSQL as a read-only mirror; the primary source of truth remains the SQLite archive.

## DuckDB and Quack Protocol Deployment

For portable analytics and offline analysis, mirror the SQLite archive to DuckDB using `agentsview duckdb push` (implemented in the built-in [`internal/duckdb/duckdb.go`](https://github.com/kenn-io/agentsview/blob/main/internal/duckdb/duckdb.go) driver wrapper). Serve the UI read-only from DuckDB with `agentsview duckdb serve`.

```bash

# Mirror to DuckDB

agentsview duckdb push --full

# Serve from DuckDB file

agentsview duckdb serve

```

### Remote Access via Quack

The DuckDB "Quack" protocol exposes the mirror over HTTP with token authentication. Run `agentsview duckdb quack serve` to start the endpoint on port 9494:

```bash
QUACK_TOKEN="$(openssl rand -base64 32)"
agentsview duckdb quack serve \
  --bind quack:0.0.0.0:9494 \
  --token "$QUACK_TOKEN" \
  --allow-insecure

```

Remote clients connect using:

```bash
AGENTSVIEW_DUCKDB_URL='quack:https://duckdb.example.com' \
AGENTSVIEW_DUCKDB_TOKEN="$QUACK_TOKEN" \
agentsview duckdb serve

```

## System Service and Background Daemon

For long-running host services, use `agentsview serve --background` to start a detached daemon. Install systemd (Linux) or launchd (macOS) units via the service install command:

```bash

# Install systemd user service

agentsview pg service install
systemctl --user enable agentsview-pg.service
systemctl --user start agentsview-pg.service

```

The service runs `agentsview pg push --watch` in the background, automatically keeping the remote PostgreSQL store synchronized with local SQLite changes.

## Desktop Application (Tauri)

For users preferring a GUI without terminal access, a native desktop wrapper bundles the binary and UI using Tauri. Distribute via Homebrew Cask or GitHub Releases for macOS and Windows environments. This deployment mode uses the same underlying [`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go) HTTP router and [`internal/db/db.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/db.go) storage layer as the binary, but packaged with a native window wrapper.

## Summary

- **Local Binary**: Single Go executable with embedded SQLite at `~/.agentsview`, served on `127.0.0.1:8080` via [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go).
- **Docker**: Official image at `ghcr.io/kenn-io/agentsview:latest` with volume mounts for data and agent sessions.
- **Docker Compose**: Production-ready orchestration via [`docker-compose.prod.yaml`](https://github.com/kenn-io/agentsview/blob/main/docker-compose.prod.yaml) with persistent volumes.
- **PostgreSQL**: Mirror SQLite to PostgreSQL using [`internal/postgres/push.go`](https://github.com/kenn-io/agentsview/blob/main/internal/postgres/push.go) for team-wide `agentsview pg serve` deployments.
- **DuckDB**: Offline analytics via `agentsview duckdb push` and remote access via the Quack protocol on port 9494.
- **System Service**: Background daemon managed by systemd or launchd using `agentsview pg service install`.
- **Desktop**: Tauri-wrapped native application for macOS/Windows.

## Frequently Asked Questions

### What is the default storage backend for agentsview?

The default storage is **SQLite with FTS5 enabled**, managed by [`internal/db/db.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/db.go). All ingestion happens into this SQLite archive first, regardless of whether you later mirror to PostgreSQL or DuckDB.

### How do I secure agentsview when exposing it beyond localhost?

By default, [`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go) binds to the loopback address and validates the `Host` header to prevent DNS-rebinding. When exposing publicly, use `--public-url` to specify your domain and `--require-auth` to enforce authentication, or place the service behind a reverse proxy with TLS termination.

### Can I deploy agentsview without using Docker?

Yes. The [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go) entry point supports standalone binary deployment. You can run the compiled Go executable directly on any system, or install the Tauri-based desktop application via Homebrew Cask for a GUI experience without containers.

### What is the difference between `pg push` and `duckdb push`?

Both are **mirroring operations** that copy data from the primary SQLite archive to secondary backends. `agentsview pg push` (defined in [`internal/postgres/push.go`](https://github.com/kenn-io/agentsview/blob/main/internal/postgres/push.go)) upserts data to PostgreSQL for team-wide dashboards, while `agentsview duckdb push` creates a portable DuckDB file for offline analytics. The SQLite archive remains the primary source of truth in both cases.