# How to Customize AgentsView Behavior: Complete Configuration Guide

> Learn how to customize AgentsView behavior using CLI flags environment variables or config.toml with clear precedence rules for easy configuration.

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

---

**Customize AgentsView by modifying the `Config` struct through CLI flags, environment variables, or a [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/config.toml)** or [`config.json`](https://github.com/kenn-io/agentsview/blob/main/config.json) files read by `applyConfigTOML` (line 62 in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go))
3. **Environment variables** parsed by `loadEnv` (line 66 in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go))
4. **CLI flags** registered in [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/config.toml) file in `$HOME/.agentsview/` to persist your customizations:

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

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

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

```go
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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go).
- **Three Input Methods**: Customize via [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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.