How to Configure a Caddy Reverse Proxy with TLS Certificates for Agentsview

Agentsview can automatically launch and manage a Caddy instance that terminates TLS and proxies traffic to the local agentsview HTTP server when you set proxy.mode = "caddy" and provide valid certificate file paths.

The kenn-io/agentsview repository ships with a built-in reverse proxy management system defined in cmd/agentsview/managed_caddy.go. Configuring a Caddy reverse proxy with TLS certificates for agentsview involves populating the proxy configuration section to trigger the managedCaddy helper, which validates your settings, generates a minimal Caddyfile, and supervises the Caddy process lifecycle.

How the Managed Caddy Integration Works

When proxy.mode is set to "caddy", agentsview executes a three-phase startup sequence implemented in cmd/agentsview/managed_caddy.go:

1. Configuration validation via validateServeConfig ensures the public_url uses HTTPS and that TLS certificate files are readable.
2. Caddyfile generation via buildManagedCaddyfile creates a configuration with TLS termination and reverse proxy rules.
3. Process management via startManagedCaddy writes the configuration to disk, validates it with caddy validate, and launches the Caddy binary.

Configuration Requirements

Before starting agentsview, you must satisfy several validation rules enforced by validateServeConfig (lines 41-56 in managed_caddy.go):

• Proxy mode: Set proxy.mode = "caddy" in your configuration or pass --proxy=caddy.
• HTTPS requirement: The public_url must use the https scheme when TLS certificates are provided. An http URL is only permitted if both tls_cert and tls_key are empty.
• TLS assets: Both proxy.tls_cert and proxy.tls_key must point to readable files verified by requireReadableFile.
• Loopback binding: The backend host must resolve to a loopback address (127.0.0.1, localhost, or ::1) via the isLoopbackHost check.

Step-by-Step Configuration

Install Caddy

Ensure the caddy binary is available on your system. The path defaults to "caddy" in your PATH, but you can specify a custom location via proxy.caddy_bin or the --caddy-bin flag.

Prepare TLS Certificates

Obtain PEM-encoded certificate and key files. The agentsview process must have read permissions for both files. Common locations include /etc/agentsview/tls/cert.pem and /etc/agentsview/tls/key.pem.

Method 1: Configuration File (config.toml)

Create or edit config.toml in your agentsview data directory (default: $HOME/.agentsview, overridable via AGENTSVIEW_DATA_DIR):

proxy.mode = "caddy"
proxy.caddy_bin = "/usr/local/bin/caddy"
proxy.bind_host = "127.0.0.1"
proxy.tls_cert = "/etc/agentsview/tls/cert.pem"
proxy.tls_key = "/etc/agentsview/tls/key.pem"
proxy.allowed_subnets = ["10.0.0.0/8", "192.168.1.0/24"]

public_url = "https://agents.example.com:8443"

The allowed_subnets field is optional and creates ACL rules in the generated Caddyfile to restrict client access to specific CIDR ranges.

Method 2: Command-Line Flags

Pass equivalent flags when running the serve command. These flags are registered in internal/config/config.go via RegisterServeFlags:

agentsview serve \
  --proxy=caddy \
  --caddy-bin=/usr/local/bin/caddy \
  --proxy-bind-host=127.0.0.1 \
  --tls-cert=/etc/agentsview/tls/cert.pem \
  --tls-key=/etc/agentsview/tls/key.pem \
  --allowed-subnet=10.0.0.0/8 \
  --public-url=https://agents.example.com:8443

Generated Caddyfile Structure

The buildManagedCaddyfile function (lines 50-88) dynamically assembles a Caddyfile. A typical generated configuration looks like this:

{
    admin off
    auto_https off
}

https://agents.example.com:8443 {
    bind 127.0.0.1
    tls "/etc/agentsview/tls/cert.pem" "/etc/agentsview/tls/key.pem"
    reverse_proxy 127.0.0.1:8080
}

This configuration disables Caddy's admin API and automatic HTTPS, binds to the specified host, terminates TLS with your certificates, and proxies to the agentsview backend. If allowed_subnets are configured, an @blocked matcher returns 403 Forbidden for clients outside the specified ranges.

Debugging and Verification

Inspect the Generated Configuration

After starting agentsview, examine the generated Caddyfile at:

cat ~/.agentsview/managed-caddy/caddy/Caddyfile

The managedCaddyConfigPath function determines this location based on your data directory and proxy mode.

Verify Caddy Validation

The startManagedCaddy function (lines 97-124) runs caddy validate before launching. If validation fails, agentsview surfaces the error immediately. Check logs for Caddy startup errors during the grace period defined by managedCaddyStartGrace.

Test the Endpoint

Once running, verify that requests to your public_url terminate TLS correctly and proxy to the agentsview UI. The system uses waitForLocalPort to ensure the backend is reachable before marking the service as ready.

Summary

• Set proxy.mode = "caddy" to enable the managed reverse proxy.
• Provide tls_cert and tls_key paths under the proxy configuration section.
• Ensure public_url uses https:// when TLS files are specified.
• The managedCaddy helper in cmd/agentsview/managed_caddy.go handles validation, Caddyfile generation, and process lifecycle.
• Generated configurations are stored in <data-dir>/managed-caddy/<mode>/Caddyfile.
• Optional allowed_subnets restricts access via Caddy ACL matchers.

Frequently Asked Questions

Can I use automatic HTTPS instead of providing my own certificates?

No. When configuring a Caddy reverse proxy with TLS certificates for agentsview in managed mode, the system explicitly disables automatic HTTPS with auto_https off and requires you to provide certificate paths via tls_cert and tls_key. This design ensures agentsview uses your specific TLS assets rather than Caddy's automatic provisioning.

What happens if the TLS certificate files are not readable?

The validateServeConfig function calls requireReadableFile on both certificate paths during startup. If either file is unreadable, agentsview exits immediately with an error before attempting to generate the Caddyfile or launch Caddy.

Can I bind the proxy to a public IP address instead of localhost?

No. The isLoopbackHost validation in managed_caddy.go enforces that the backend address must resolve to 127.0.0.1, localhost, or ::1. This security measure ensures the agentsview HTTP server remains inaccessible from external networks, with Caddy acting as the controlled entry point. You can configure proxy.bind_host to control where Caddy listens, but the backend must remain on loopback.

Where does agentsview store the generated Caddyfile?

The managedCaddyConfigPath function writes the Caddyfile to <data-dir>/managed-caddy/<mode>/Caddyfile, where <data-dir> defaults to $HOME/.agentsview (or the path set by AGENTSVIEW_DATA_DIR) and <mode> is the proxy mode (typically caddy).

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