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

AgentsView loads configuration from four layered sources—hardcoded defaults in 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:

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:

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

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

[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):

[[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
• 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, 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 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.

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