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

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, 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. 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 within the Serve flag set (lines 140-159) and passed to server.WithBasePath.

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

# 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:

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:

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

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:

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: Contains the WithBasePath option implementation, base-path-aware OpenAPI configuration, and SPA handling logic for asset rewriting and <base> injection.
• 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: Defines the CLI structure; the serve command retrieves the flag value and passes it to the server configuration.
• 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 and exposed via 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, 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. 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, which implements the WithBasePath option and handles request URL stripping and SPA HTML modification. The 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.

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