How to Customize AgentsView Behavior: Complete Configuration Guide

Customize AgentsView by modifying the Config struct through CLI flags, environment variables, or a config.toml file, with settings merged in strict precedence from flags down to hardcoded defaults.

AgentsView is a Go-based agent session viewer that centralizes all runtime behavior—from HTTP server binding to TLS termination and database sync—in a single configuration object. To customize AgentsView behavior, you manipulate the Config struct defined in internal/config/config.go, which supports hierarchical overrides via command-line arguments, environment variables, and TOML configuration files. This guide provides concrete examples for the most common customization scenarios based on the actual source code implementation.

Configuration Hierarchy and Precedence

The Central Config Struct

All runtime-adjustable behavior in AgentsView flows through the Config struct located in internal/config/config.go. This struct aggregates settings for network binding, authentication, proxy management, terminal integration, database connections, and per-agent overrides. According to the AgentsView source code, every component—including the HTTP server, Caddy proxy, sync engine, and session parsers—reads its behavior from this central configuration object.

Configuration Loading Order

The configuration system merges values in the following order of precedence, where later sources override earlier ones:

1. Hardcoded defaults defined in the Config struct initialization
2. config.toml or config.json files read by applyConfigTOML (line 62 in internal/config/config.go)
3. Environment variables parsed by loadEnv (line 66 in internal/config/config.go)
4. CLI flags registered in cmd/agentsview/main.go via RegisterServeFlags and applied by applyFlags

This hierarchy means that environment variables override file settings, and command-line flags take ultimate precedence over all other sources.

Core Customization Areas

Network and UI Binding

Control the embedded HTTP server behavior using these Config fields:

• Host and Port: Define the bind address and TCP port (default: localhost:8080)
• PublicURL: The external URL used for generating links and CORS headers
• PublicOrigins: Trusted CORS origins for the frontend SPA
• RequireAuth and AuthToken: Enable API authentication by requiring a bearer token

These values are consumed by the server initialization logic in internal/server/server.go.

Managed Reverse Proxy Configuration

AgentsView can automatically launch a Caddy instance to handle TLS termination and reverse proxying. Configure this via the Proxy struct field:

• Mode: Set to "caddy" to enable the managed proxy
• Bin: Path to the Caddy binary (default: /usr/local/bin/caddy)
• BindHost and PublicPort: Where the proxy listens (e.g., 0.0.0.0:443)
• TLSCert and TLSKey: Paths to your TLS certificate files
• AllowedSubnets: CIDR blocks to restrict access (e.g., ["10.0.0.0/8"])

The proxy configuration is validated and initialized during the serve command execution.

Terminal Integration Settings

Customize how the resume command opens terminal sessions using the Terminal field:

• Mode: Options include auto, tmux, screen, or custom
• CustomBin: Specify a custom terminal binary (e.g., /usr/bin/konsole)
• CustomArgs: Arguments passed to the terminal binary, supporting {cmd} placeholder substitution

This integration is particularly useful when running AgentsView inside containerized or remote development environments.

Database Synchronization

AgentsView supports optional backends for session persistence and analytics:

PostgreSQL Sync via the PG field:

• URL: Connection string (can be overridden by AGENTSVIEW_PG_URL)
• PGTargets: Map of named connection targets for fan-out scenarios
• DefaultPG: Which target to use by default

DuckDB Mirror via the DuckDB field:

• Path: Local file path for the DuckDB database
• URL and Token: Remote DuckDB server credentials

Connection handling is implemented in internal/postgres/connect.go and respects the pgEnvOverrides for environment-based credentials.

Automated Classification Rules

Extend the session classifier with domain-specific matching rules using the Automated field:

• Prefixes: Array of string prefixes (e.g., ["TODO:", "FIXME:"])
• Substrings: Substring matches (e.g., ["🚧", "🔒"])
• ExactMatches: Exact string matches (e.g., ["UNSAFE"])

These rules are merged into the classifier at startup in internal/parser/classifier.go to improve search relevance and automatic categorization.

Per-Agent Runtime Overrides

Override launch behavior for specific agents using the Agent map, which maps agent names to AgentConfig structs:

• Binary: Custom path to the agent executable
• Sandbox: Execution environment (e.g., "docker", "none")
• AllowUnsafe: Permit potentially unsafe operations for this agent

This allows you to use custom-built agent binaries or enforce specific sandboxing policies per agent type.

Practical Implementation Examples

Creating a Custom config.toml

Place a config.toml file in $HOME/.agentsview/ to persist your customizations:

host = "0.0.0.0"
port = 9090
require_auth = true
auth_token = "secure-token-123"

[proxy]
mode = "caddy"
bin = "/usr/local/bin/caddy"
bind_host = "0.0.0.0"
public_port = 443
tls_cert = "/etc/agentsview/tls.crt"
tls_key = "/etc/agentsview/tls.key"
allowed_subnets = ["10.0.0.0/8", "192.168.1.0/24"]

[terminal]
mode = "custom"
custom_bin = "/usr/bin/konsole"
custom_args = "--new-tab -e {cmd}"

[agent."myagent"]
binary = "/opt/myagent/bin/agent"
sandbox = "docker"
allow_unsafe = true

[automated]
prefixes = ["TODO:", "FIXME:", "NOTE:"]
substrings = ["🚧", "🔒"]
exact_matches = ["UNSAFE"]

This configuration exposes AgentsView on all interfaces with TLS termination, uses Konsole for resume commands, and applies custom rules for a specific agent named myagent.

Overriding via Environment Variables

For containerized deployments or CI/CD pipelines, use the AGENTSVIEW_ prefix:

export AGENTSVIEW_HOST=127.0.0.1
export AGENTSVIEW_PORT=8081
export AGENTSVIEW_PROXY=caddy
export AGENTSVIEW_PROXY_PUBLIC_PORT=8443
export AGENTSVIEW_PG_URL=postgres://pguser:secret@db.example.com/agentsview?sslmode=require
export AGENTSVIEW_DUCKDB_PATH=/var/lib/agentsview/duckdb.db

These variables are parsed by the loadEnv function in internal/config/config.go (lines 66-84) and take precedence over file-based configuration.

Runtime CLI Flags

Pass flags directly to the serve command for temporary overrides:

agentsview serve \
  --host 0.0.0.0 \
  --port 8080 \
  --proxy caddy \
  --caddy-bin /opt/caddy/bin/caddy \
  --tls-cert /opt/certs/agentsview.crt \
  --tls-key /opt/certs/agentsview.key \
  --allowed-subnet 10.10.0.0/16 \
  --no-browser \
  --events-coalesce-interval 5s

Flags are registered in RegisterServeFlags (sourced from cmd/agentsview/main.go) and applied via applyFlags/applyPFlags in the config package.

Programmatic Configuration in Go

For advanced integrations, manipulate the configuration struct directly before starting the server:

cfg, _ := config.LoadMinimal()

// Add a remote sync target
cfg.RemoteHosts = append(cfg.RemoteHosts, config.RemoteHost{
    Host:      "sync.example.com",
    Transport: config.RemoteTransportSSH,
    User:      "syncuser",
    Port:      22,
    Interval:  15 * time.Minute,
})

// Validate remote host configuration
if err := cfg.ValidateRemoteHosts(); err != nil {
    log.Fatal(err)
}

The ValidateRemoteHosts function (lines 39-76 in internal/config/config.go) ensures that invalid entries cause immediate, clear errors before the sync process begins.

Summary

• Centralized Configuration: All AgentsView behavior is controlled by the Config struct in internal/config/config.go.
• Three Input Methods: Customize via config.toml files, AGENTSVIEW_ prefixed environment variables, or CLI flags.
• Strict Precedence: Command-line flags override environment variables, which override config files, which override defaults.
• Key Areas: Network binding, Caddy proxy settings, terminal integration, PostgreSQL/DuckDB sync, automated classification rules, and per-agent binary overrides.
• Validation: Remote sync targets and proxy configurations are validated at startup to prevent runtime errors.

Frequently Asked Questions

What is the configuration precedence order in AgentsView?

AgentsView merges configuration in the following order: hardcoded defaults are loaded first, then overridden by values from config.toml (processed by applyConfigTOML), then by environment variables parsed by loadEnv, and finally by CLI flags applied via applyFlags. This means that command-line arguments always take the highest precedence.

How do I enable TLS for the AgentsView web interface?

Set the proxy.mode field to "caddy" in your configuration, then provide paths to your certificate and key files using proxy.tls_cert and proxy.tls_key. Ensure the proxy.public_port is set to 443 and that the Caddy binary path is correctly specified in proxy.bin. The managed proxy will automatically terminate TLS and forward traffic to the internal AgentsView server.

Can I customize classification rules for agent sessions?

Yes, extend the automated classifier by adding entries to the [automated] section in your config.toml. Use the prefixes, substrings, and exact_matches arrays to define domain-specific patterns. These rules are merged into the classifier at startup in internal/parser/classifier.go and improve the relevance of automatic session categorization.

How do I configure remote sync targets programmatically?

Import the internal/config package and append RemoteHost structs to the cfg.RemoteHosts slice. Specify the Host, Transport (SSH or HTTP), User, Port, and Interval fields. Call ValidateRemoteHosts() to ensure the configuration is valid before starting the sync process. Invalid configurations will abort with clear error messages indicating which host failed validation.

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