# How to Configure the Base Path for Reverse Proxy Deployments of AgentsView

> Learn to configure the AgentsView base path for reverse proxy deployments using CLI flags or server options. Ensure correct routing and SPA functionality behind sub-URL mounts.

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

---

**AgentsView supports reverse-proxy deployments via the `--base-path` CLI flag or `WithBasePath()` server option, which strips URL prefixes, injects a `<base href>` tag into the SPA, and rewrites asset paths to ensure correct routing behind sub-URL mounts.**

When deploying the **AgentsView** observability platform behind a reverse proxy such as Nginx, Caddy, or Traefik, you must configure the base path to align the application’s routing and asset resolution with the external URL mount point. This configuration ensures that requests to `/agentsview/api/v1/...` are correctly routed internally and that the single-page application (SPA) loads static assets from the proper subdirectory.

## How the Base Path Configuration Works

The base path mechanism in AgentsView performs three critical functions to support reverse-proxy deployments:

1. **URL Prefix Stripping**: Incoming request URLs have the configured prefix removed before routing to API handlers.
2. **SPA Base Tag Injection**: The server injects a `<base href="/your-path/">` tag into the embedded SPA’s [`index.html`](https://github.com/kenn-io/agentsview/blob/main/index.html), ensuring all relative asset URLs resolve correctly.
3. **Asset URL Rewriting**: Root-relative asset references (`href="/..."` and `src="/..."`) are rewritten to include the base path prefix.

This logic is implemented in **[`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go)**. The `WithBasePath(path string)` option stores the trimmed prefix in `Server.basePath` (lines 76-84). When a base path is set, the OpenAPI server description automatically includes it so generated documentation displays the correct external URLs (lines 26-33). The SPA handler subsequently rewrites asset links and injects the `<base>` tag when `Server.basePath` is non-empty (lines 94-108).

## Configuring the Base Path via Command Line

The most common deployment method uses the `--base-path` flag registered in the `serve` command. This flag is defined in **[`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go)** within the `Serve` flag set (lines 140-159) and passed to `server.WithBasePath`.

The value must start with `/` and must **not** end with `/`.

```bash

# Serve AgentsView at http://example.com/agentsview

agentsview serve --base-path /agentsview \
    --host 0.0.0.0 \
    --port 8080

```

With this configuration, the API serves under `/agentsview/api/v1/...` and the SPA loads static assets from `/agentsview/static/...`.

## Programmatic Configuration

When embedding AgentsView into another Go application, use the functional option pattern to configure the base path directly:

```go
import (
    "net/http"
    "go.kenn.io/agentsview/internal/server"
)

func main() {
    s := server.New(
        server.WithBasePath("/myapp"),
        // Additional options: server.WithDataDir(), server.WithBroadcaster(), etc.
    )
    
    // Start the HTTP server
    http.ListenAndServe(":8080", s.Handler())
}

```

This approach instantiates the server with the base path stored internally, applying the same URL stripping and HTML rewriting logic as the CLI method.

## Docker and Reverse Proxy Examples

### Docker Compose Configuration

Deploy AgentsView in a container with the base path pre-configured:

```yaml
services:
  agentsview:
    image: ghcr.io/kenn-io/agentsview:latest
    command: ["serve", "--base-path", "/viewer", "--host", "0.0.0.0", "--port", "80"]
    ports:
      - "8080:80"

```

When your reverse proxy forwards `example.com/viewer/*` to port 8080, the application handles path stripping and asset resolution automatically without requiring additional proxy rewrite rules.

### Caddy Reverse Proxy

```caddy
example.com {
    reverse_proxy localhost:8080 {
        uri /viewer{uri}
    }
    
    handle_path /viewer/* {
        # AgentsView handles base path internally; no extra configuration required

    }
}

```

### Nginx Configuration Pattern

For Nginx, proxy requests to the AgentsView container while preserving the path:

```nginx
location /agentsview/ {
    proxy_pass http://agentsview:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Prefix /agentsview;
}

```

## Key Implementation Files

Understanding the source structure helps when debugging reverse-proxy issues:

- **[`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go)**: Contains the `WithBasePath` option implementation, base-path-aware OpenAPI configuration, and SPA handling logic for asset rewriting and `<base>` injection.
- **[`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go)**: Registers the `--base-path` flag for the `serve` command via `RegisterServePFlags` and wires it to the server constructor.
- **[`cmd/agentsview/cli.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/cli.go)**: Defines the CLI structure; the `serve` command retrieves the flag value and passes it to the server configuration.
- **[`internal/server/basepath_test.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/basepath_test.go)**: Unit tests verifying URL stripping, redirects, asset rewriting, and SPA fallback behavior when a base path is active.

## Summary

- AgentsView uses the **`--base-path`** CLI flag or **`WithBasePath()`** Go option to support reverse-proxy sub-path deployments.
- The server automatically **strips the prefix** from incoming requests, **injects a `<base href>` tag** into the SPA, and **rewrites root-relative asset URLs**.
- The base path must start with `/` and cannot end with `/` (e.g., `/agentsview` is valid; `/agentsview/` is not).
- Configuration is handled in **[`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go)** and exposed via **[`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go)**.
- No additional URL rewriting is required at the reverse-proxy layer when the base path is correctly configured.

## Frequently Asked Questions

### What is the correct format for the --base-path value?

The `--base-path` value must be an absolute path starting with `/` and must not include a trailing slash. For example, `/agentsview` is valid, but `/agentsview/` or `agentsview` will cause configuration errors or routing failures according to the validation logic in the AgentsView source code.

### How does AgentsView handle asset URLs when behind a reverse proxy?

When a base path is configured, AgentsView rewrites root-relative asset URLs (such as `href="/static/..."` or `src="/js/..."`) to include the base path prefix. Additionally, it injects a `<base href="/your-base-path/">` tag into the SPA’s [`index.html`](https://github.com/kenn-io/agentsview/blob/main/index.html), ensuring that relative URLs resolve correctly regardless of the current route depth.

### Can I configure the base path using environment variables?

The standard distribution uses CLI flags defined in **[`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go)**. While the code accepts the base path via the `WithBasePath()` functional option when embedding the server, native environment variable support depends on your deployment wrapper. In Docker Compose, you can pass the flag via the `command` array as shown in the examples above.

### Which files handle the base path logic in the source code?

The core logic resides in **[`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go)**, which implements the `WithBasePath` option and handles request URL stripping and SPA HTML modification. The **[`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go)** file registers the `--base-path` flag and binds it to the server configuration. Unit tests verifying this behavior are located in **[`internal/server/basepath_test.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/basepath_test.go)**.