Best Practices for Using agentsview: Secure Self-Hosted AI Session Management

Run agentsview as a background daemon to maintain a warm SQLite archive, secure remote access with explicit origin validation, and mirror session data to PostgreSQL or DuckDB for team analytics while storing sensitive credentials in restrictive configuration files.

agentsview is a local, self-hosted viewer that indexes AI-coding-agent sessions into a SQLite archive with optional PostgreSQL or DuckDB mirrors, serving a Svelte 5 web UI via a tiny Go server. Following these best practices ensures optimal performance, security, and data portability across the architecture defined in kenn-io/agentsview.

Run the Daemon for Warm Archives and Real-Time Sync

The sync engine in internal/sync/engine.go maintains database warmth through a background daemon that watches session directories and performs periodic ingestion every 15 minutes. Running as a daemon avoids the cold-start cost of re-scanning entire disk hierarchies when launching the web UI.

Start the daemon detached from your terminal:

agentsview serve --background

Verify the daemon status and stop it when maintenance is required:

agentsview serve status
agentsview serve stop

The CLI automatically restarts the daemon for commands requiring fresh data, such as agentsview usage or agentsview pg push, as implemented in cmd/agentsview/daemon_runtime.go.

Secure Remote Access with Explicit Origins

The HTTP server in internal/server/server.go binds to 127.0.0.1 by default and validates the Host header to prevent DNS-rebinding attacks. When exposing the UI through SSH forwarding or reverse proxies, explicitly declare the public origin to prevent header validation failures.

Forward a port via SSH and specify the public URL:

ssh -L 18080:127.0.0.1:8080 remote
agentsview serve --public-url http://127.0.0.1:18080

For multiple origins, use the comma-separated --public-origin flag. Enable --require-auth when exposing the service to untrusted networks to enforce authentication checks before serving the Svelte 5 SPA embedded in internal/web/dist.

Configure Secrets Safely in config.toml

The configuration loader in internal/config/config.go parses ~/.agentsview/config.toml, environment variables, and CLI flags in that order of precedence. Store database credentials and API keys in the TOML file with restrictive permissions (chmod 600) to prevent unauthorized access.

Create a secure configuration for PostgreSQL sync:

# ~/.agentsview/config.toml

[pg.work]
url = "postgres://user:pass@work-db/agentsview"
machine_name = "laptop"

Override agent-specific directories using environment variables like CLAUDE_PROJECTS_DIR or AIDER_DIR to keep project paths flexible across machines without hardcoding absolute paths in the config file.

Track Token Usage and Costs Natively

Replace external tools like ccusage with the built-in agentsview usage command, which draws pricing from LiteLLM rates with offline fallback support and computes cache-aware costs automatically. The command queries the SQLite archive maintained by internal/db/db.go with FTS5 full-text search capabilities.

Generate daily cost summaries for the last 30 days:

agentsview usage daily

Export JSON for integration with status bars or automation scripts:

agentsview usage daily --all --json

Filter by agent, date range, and timezone for detailed breakdowns:

agentsview usage daily \
  --agent claude \
  --since 2026-01-01 \
  --timezone America/Los_Angeles \
  --breakdown \
  --json

Mirror Data to PostgreSQL or DuckDB

The database layer in internal/db/db.go supports read-only mirrors to PostgreSQL for team dashboards and DuckDB for portable analytics. The primary SQLite archive remains the source of truth, ensuring data integrity while enabling flexible query patterns.

Configure a named PostgreSQL target in config.toml:

default_pg = "work"
[pg.work]
url = "postgres://user:pass@db.example.com/agentsview"
machine_name = "laptop"

Push all sessions to the remote database:

agentsview pg push --all

Create a portable DuckDB mirror for Python or R analysis:

agentsview duckdb push
agentsview duckdb serve

The DuckDB serve mode provides a read-only UI that queries the .duckdb file directly without write access to the primary SQLite store.

Use the Desktop Tauri Wrapper for Native Experience

The desktop application bundles the Go server and Svelte 5 UI within a Tauri wrapper, providing a native tray icon and system integration without requiring terminal management. Install via Homebrew or download from GitHub releases.

Install and launch the macOS desktop app:

brew install --cask agentsview
open -a AgentsView

The desktop code resides in desktop/ and is built by the make install target, sharing the same internal/server/server.go logic as the CLI version but with additional OS-native window management.

Maintain Test Coverage and Recent Dependencies

The project requires Go 1.26+ (with CGO enabled for SQLite) and Node 22+ for the frontend build system. Before contributing or upgrading versions, validate changes against the full test matrix to ensure the parser registry in internal/parser/types.go and sync engine remain functional.

Execute the complete validation suite:

make test
make e2e
make lint

The Go tests exercise SQLite and FTS5 functionality, while Playwright end-to-end tests verify the Svelte 5 SPA's API client integration against the REST endpoints defined in internal/server/server.go.

Manage Telemetry and Privacy Settings

Telemetry collection is opt-out via the environment variable AGENTSVIEW_TELEMETRY_ENABLED=0. The payload contains only installation ID, version, and operating system metrics—never session content, project names, or user-identifiable data.

Disable telemetry before starting the server:

export AGENTSVIEW_TELEMETRY_ENABLED=0
agentsview serve --background

Refer to the Privacy section in the repository documentation for the complete schema of transmitted fields.

Summary

• Run the daemon using agentsview serve --background to eliminate cold-start delays and enable real-time file watching via internal/sync/engine.go.
• Secure remote access by setting --public-url or --public-origin when proxying, and enable --require-auth for untrusted networks.
• Protect credentials in ~/.agentsview/config.toml with chmod 600 permissions, parsed by internal/config/config.go.
• Track costs natively with agentsview usage instead of external tools, leveraging the SQLite archive with LiteLLM pricing data.
• Mirror to PostgreSQL for team dashboards or DuckDB for portable analytics, keeping SQLite as the primary source of truth.
• Use the desktop app via Homebrew (brew install --cask agentsview) for a native Tauri-wrapped experience.
• Maintain dependencies at Go 1.26+ and Node 22+, running make test and make e2e before deployment.
• Control telemetry by setting AGENTSVIEW_TELEMETRY_ENABLED=0 to opt-out of anonymous usage statistics.

Frequently Asked Questions

How do I add support for a new AI agent not currently indexed?

Create a custom session directory entry in ~/.agentsview/config.toml pointing to the agent's log output location, then implement a parser in internal/parser/types.go following the existing Claude, Codex, and Cursor patterns. The sync engine in internal/sync/engine.go automatically discovers and ingests files matching the parser's glob patterns during the next periodic scan or file system event.

Can I run agentsview without the background daemon?

Yes, but running agentsview serve without --background triggers a cold start where the sync engine must re-scan all configured directories before serving the UI, causing significant latency on large codebases. For production use, always run the daemon to maintain a warm SQLite archive with FTS5 indexes ready for immediate queries.

What is the difference between PostgreSQL and DuckDB mirroring?

PostgreSQL mirroring via agentsview pg push is designed for team dashboards and shared analytics, requiring a running PostgreSQL server with write access. DuckDB mirroring via agentsview duckdb push creates a portable, single-file database ideal for local analysis in Python or R, with agentsview duckdb serve providing a read-only web interface that cannot modify the primary SQLite archive.

How do I troubleshoot sync failures or missing sessions?

Check the daemon logs using agentsview serve status to locate the log file path, then verify that your session directories are correctly listed in config.toml or environment variables like CLAUDE_PROJECTS_DIR. Ensure the parser registry in internal/parser/types.go contains a valid parser for your agent's log format, and confirm the database migrations in internal/db/db.go have completed successfully by checking the SQLite schema version.

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