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

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

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

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 file. This configuration persists the data volume and can be integrated with reverse proxies like Traefik or Nginx.

# 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 upserts rows into the sessions and messages tables defined in internal/postgres/schema.go.

# 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 driver wrapper). Serve the UI read-only from DuckDB with agentsview duckdb serve.

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

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:

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:

# 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 HTTP router and 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.
• 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 with persistent volumes.
• PostgreSQL: Mirror SQLite to PostgreSQL using 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. 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 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 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) 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.

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