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

> Effortlessly configure a Caddy reverse proxy with TLS for Agentsview. Automate TLS termination and traffic proxying by setting proxy mode and providing certificate paths. Secure your Agentsview instance.

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

---

**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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/config.toml) in your agentsview data directory (default: `$HOME/.agentsview`, overridable via `AGENTSVIEW_DATA_DIR`):

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

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

```text
{
    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:

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