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

> Master agentsview best practices for secure self-hosted AI session management. Run as a daemon, secure access, and mirror data for analytics. Learn more.

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

---

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

```bash
agentsview serve --background

```

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

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

## Secure Remote Access with Explicit Origins

The HTTP server in [`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/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:

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

```toml

# ~/.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`](https://github.com/kenn-io/agentsview/blob/main/internal/db/db.go) with FTS5 full-text search capabilities.

Generate daily cost summaries for the last 30 days:

```bash
agentsview usage daily

```

Export JSON for integration with status bars or automation scripts:

```bash
agentsview usage daily --all --json

```

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

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

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

```

Push all sessions to the remote database:

```bash
agentsview pg push --all

```

Create a portable DuckDB mirror for Python or R analysis:

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

```bash
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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) and sync engine remain functional.

Execute the complete validation suite:

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

```bash
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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) following the existing Claude, Codex, and Cursor patterns. The sync engine in [`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/config.toml) or environment variables like `CLAUDE_PROJECTS_DIR`. Ensure the parser registry in [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) contains a valid parser for your agent's log format, and confirm the database migrations in [`internal/db/db.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/db.go) have completed successfully by checking the SQLite schema version.