# AgentsView Configuration Options: Complete Guide to TOML, Environment Variables, and CLI Flags

> Master AgentsView configuration using TOML, environment variables, and CLI flags. This guide details all options for complete control. Explore the AgentsView config schema now.

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

---

**AgentsView loads configuration from four layered sources—hardcoded defaults in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go), a TOML file at `$AGENTSVIEW_DATA_DIR/config.toml`, environment variables, and CLI flags—with later sources overriding earlier ones.** The complete configuration schema is defined in the `Config` struct starting at line 30 of the `kenn-io/agentsview` repository, allowing you to control everything from HTTP server binding to PostgreSQL synchronization and TLS termination.

## How AgentsView Loads Configuration

The configuration pipeline follows a strict precedence order implemented in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go):

1. **Default values** – Initialized by the `Default()` function
2. **TOML file** – Parsed by `Config.applyConfigTOML` (lines 640–720)
3. **Environment variables** – Loaded by `Config.loadEnv` (lines 660–720)
4. **CLI flags** – Registered in `RegisterServeFlags` and `RegisterServePFlags` (lines 540–620), then applied via `applyFlags` and `applyPFlags` (lines 830–880)

The final resolved configuration is stored in the `Config` struct, which contains fields for server settings, database connections, proxy rules, and agent-specific overrides.

## Server and Networking Configuration

Control the HTTP server behavior using these options defined in the `Config` struct:

| Field | TOML Key | Environment Variable | CLI Flag | Description |
|-------|----------|---------------------|----------|-------------|
| `Host` | `host` | – | `--host` | Bind interface (default `127.0.0.1`) |
| `Port` | `port` | – | `--port` | TCP port (default `8080`) |
| `PublicURL` | `public_url` | – | `--public-url` | External URL behind reverse proxies |
| `PublicOrigins` | `public_origins` | – | `--public-origin` | Allowed CORS origins (repeatable) |
| `NoBrowser` | – | – | `--no-browser` | Suppress automatic browser launch |
| `DisableUpdateCheck` | `disable_update_check` | `AGENTSVIEW_DISABLE_UPDATE_CHECK` | `--no-update-check` | Disable update-check endpoint |
| `RequireAuth` | `require_auth` | – | `--require-auth` | Enforce bearer token for all API calls |
| `EventsCoalesceInterval` | `events_coalesce_interval` | – | `--events-coalesce-interval` | SSE broadcast throttle (e.g., `5s`) |
| `DaemonIdleTimeout` | `daemon_idle_timeout` | – | – | Background daemon exit timeout |

**Example TOML configuration:**

```toml
host = "0.0.0.0"
port = 8080
public_url = "https://agents.example.com"
public_origins = ["https://agents.example.com", "https://admin.example.com"]
require_auth = true
events_coalesce_interval = "5s"

```

## Data Storage and Database Configuration

The `DataDir` field (set via `AGENTSVIEW_DATA_DIR` or `AGENT_VIEWER_DATA_DIR` fallback) determines where AgentsView stores its SQLite database (`sessions.db`) and the [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml) file.

### PostgreSQL Synchronization

Configure PostgreSQL targets using the `PGTargets` map for multi-database synchronization:

| Field | TOML Key | Environment Variable | Description |
|-------|----------|---------------------|-------------|
| `PG` / `PGTargets` | `[pg.NAME]` | `AGENTSVIEW_PG_URL`, `AGENTSVIEW_PG_SCHEMA`, `AGENTSVIEW_PG_MACHINE` | Connection parameters |

```toml
[pg.mydb]
url = "postgres://user:pass@pg.example.com:5432/agentsview?sslmode=require"
schema = "public"
machine_name = "pg-01"
allow_insecure = false
projects = ["myproject"]

```

### DuckDB and Custom Pricing

- **DuckDB**: Configure via `AGENTSVIEW_DUCKDB_PATH`, `AGENTSVIEW_DUCKDB_URL`, `AGENTSVIEW_DUCKDB_TOKEN`, and `AGENTSVIEW_DUCKDB_MACHINE`
- **Custom Model Pricing**: Define per-model cost rates in `custom_model_pricing` for input/output token billing

## Reverse Proxy and TLS Configuration

AgentsView can manage a Caddy reverse proxy when `Proxy.Mode` is set to `"caddy"`. Configuration parsing is handled by `normalizeProxyConfig` (lines 1500–1540).

| Field | TOML Key | CLI Flag | Description |
|-------|----------|----------|-------------|
| `Proxy.Mode` | `proxy.mode` | `--proxy` | Proxy type (only `"caddy"` supported) |
| `Proxy.Bin` | `proxy.bin` | `--caddy-bin` | Path to caddy executable |
| `Proxy.BindHost` | `proxy.bind_host` | `--proxy-bind-host` | Proxy bind interface |
| `Proxy.PublicPort` | `proxy.public_port` | `--public-port` | External HTTPS port (default `8443`) |
| `Proxy.TLSCert` / `Proxy.TLSKey` | `proxy.tls_cert` / `proxy.tls_key` | `--tls-cert` / `--tls-key` | Certificate paths |
| `Proxy.AllowedSubnets` | `proxy.allowed_subnets` | `--allowed-subnet` | CIDR allowlist (repeatable) |

## Session Handling and Privacy Controls

Control how AgentsView processes session data and file-watching:

- **`WatchExcludePatterns`** (`watch_exclude_patterns`): Glob patterns like `.git` and `node_modules` ignored by the file watcher
- **`ResultContentBlockedCategories`** (`result_content_blocked_categories`): Categories (`Read`, `Glob`, etc.) stripped from results for privacy compliance
- **`CursorSecret`** (`cursor_secret`): Auto-generated secret for resumable cursor IDs, created on first run by `ensureCursorSecret` (lines 880–910)
- **Cursor Admin Credentials**: Set via `AGENTSVIEW_CURSOR_ADMIN_API_KEY`, `AGENTSVIEW_CURSOR_ADMIN_EMAIL`, and `AGENTSVIEW_CURSOR_ADMIN_USER_ID`

## Per-Agent Customization

Override settings for specific agent types using the `Agent` map in the configuration:

```toml
[agent.claude]
binary = "/usr/local/bin/claude-custom"
sandbox = true
allow_unsafe = false

```

- **`Binary`**: Custom agent executable path
- **`Sandbox`**: Sandbox configuration object
- **`AllowUnsafe`**: Permit unsafe operations for that agent

Agent directories can also be set via environment variables following the pattern `<AGENTTYPE>_DIR` or through the `Config.AgentDirs` map populated in `Default()`.

## Remote Synchronization (Fan-Out)

Configure multi-host synchronization targets in the `RemoteHosts` array (validated by `Config.ValidateRemoteHosts` at lines 380–430):

```toml
[[remote_hosts]]
host = "sync-01.example.com"
transport = "ssh"
user = "sync"
port = 22

[[remote_hosts]]
host = "sync-http.example.com"
transport = "http"
url = "https://sync-http.example.com/agentsview"
token = "s3cr3t"
interval = "10m"

```

Each host supports `transport` (either `ssh` or `http`), `interval` for periodic sync, and authentication credentials. An interval of zero disables periodic synchronization for that host.

## Authentication and Security Settings

- **`AuthToken`** (`auth_token` / `AGENTSVIEW_AUTH_TOKEN`): Bearer token clients must present in the `Authorization` header when `RequireAuth` is enabled
- **`NoSync`**: Runtime flag (`--no-sync`) to disable initial sync and background file watching
- **`Terminal`**: Controls terminal launch behavior with `mode` options (`auto`, `custom`, `clipboard`)

## Summary

- **Four-layer configuration**: Defaults → TOML → Environment → CLI flags, implemented in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go)
- **Server control**: Bind addresses, CORS origins, and authentication via `host`, `port`, `public_origins`, and `require_auth`
- **Database flexibility**: SQLite by default, with optional PostgreSQL and DuckDB synchronization through environment variables or TOML tables
- **Proxy management**: Built-in Caddy integration with TLS certificate configuration via `proxy.tls_cert` and `proxy.tls_key`
- **Privacy features**: Block sensitive result categories and exclude file patterns using `result_content_blocked_categories` and `watch_exclude_patterns`
- **Multi-host sync**: Define remote targets in `[[remote_hosts]]` arrays with SSH or HTTP transport

## Frequently Asked Questions

### What is the order of precedence for AgentsView configuration options?

AgentsView applies configuration in four stages with increasing priority: first it loads hardcoded defaults from the `Default()` function in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go), then merges values from `$AGENTSVIEW_DATA_DIR/config.toml` via `applyConfigTOML`, then overrides with environment variables via `loadEnv`, and finally applies CLI flags through `applyFlags` and `applyPFlags`. A parameter defined in the TOML file can be overridden by an environment variable, which can itself be overridden by a command-line flag.

### How do I configure PostgreSQL synchronization in AgentsView?

Define PostgreSQL targets using named tables in your TOML configuration under the `[pg.NAME]` section, specifying `url`, `schema`, `machine_name`, and `projects`. Alternatively, set the legacy connection via the `AGENTSVIEW_PG_URL`, `AGENTSVIEW_PG_SCHEMA`, and `AGENTSVIEW_PG_MACHINE` environment variables. The configuration supports multiple targets through the `PGTargets` map for fan-out synchronization scenarios.

### Where does AgentsView store its configuration and database files?

AgentsView stores runtime data in the directory specified by `AGENTSVIEW_DATA_DIR` (falling back to `AGENT_VIEWER_DATA_DIR` if undefined). This directory contains both the [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml) file and the SQLite database at `sessions.db`. The cursor secret and other runtime artifacts are also persisted in this location, with the secret generated automatically by `ensureCursorSecret` if not present.

### Can I disable the automatic browser launch when starting AgentsView?

Yes, use the `--no-browser` CLI flag or set the corresponding `NoBrowser` field in your configuration. This flag is processed during server initialization and prevents AgentsView from automatically opening a web browser window when the HTTP server starts listening.