Configuration

Address and port the HTTP server binds to. Use 0.0.0.0:9000 to listen on all interfaces, or 127.0.0.1:9000 to restrict to localhost.

URL prefix for hosting Cetacean under a sub-path behind a reverse proxy (e.g., /cetacean serves the dashboard at https://example.com/cetacean/). Leave unset when Cetacean owns the root path.

Docker Engine API endpoint. Supports Unix sockets (unix:///path), TCP (tcp://host:port), and SSH (ssh://user@host).

Base URL of a Prometheus server (e.g., http://prometheus:9090). When set, Cetacean proxies metric queries and enables resource usage charts, sizing recommendations, and the metrics stream. When unset, all metric-dependent features are disabled.

Minimum log severity. One of debug, info, warn, or error.

Log output format. json produces structured, machine-readable lines. text produces human-friendly console output.

Expose Go runtime profiling endpoints at /debug/pprof/. Useful for diagnosing CPU, memory, and goroutine issues in production. Should be disabled unless actively profiling.

Expose a Prometheus-compatible metrics endpoint at /-/metrics with internal counters for SSE connections, cache operations, and HTTP request latency.

Enable the recommendation engine, which periodically analyzes swarm state and Prometheus metrics to surface suggestions (resource sizing, missing health checks, operational issues). See Recommendations for details.

Controls which write operations the dashboard exposes. 0 is fully read-only, 1 allows operational actions (scale, restart, rollback), 2 adds service configuration edits, and 3 enables destructive operations like node removal. See Operations Level for the full breakdown.

How long the SSE broadcaster waits to batch multiple change events into a single push. Lower values reduce UI update latency; higher values reduce network overhead when many resources change at once. Accepts any Go duration string (e.g., 50ms, 1s).

Origins allowed to make cross-origin requests to the API. Comma-separated list of origins (e.g., https://admin.example.com) or * to allow all. When unset, CORS headers are not sent and cross-origin requests from browsers are blocked.

IP addresses or CIDR ranges of reverse proxies whose X-Forwarded-For headers should be trusted for determining the real client IP (e.g., 10.0.0.0/8,172.16.0.0/12). Required for header-based authentication. When unset, all requests are treated as direct connections.

Persist swarm state to disk after every sync. On restart, Cetacean loads the snapshot to serve data immediately while the live sync catches up, avoiding a blank dashboard during startup.

Directory where the snapshot file (snapshot.json) is stored. Must be writable by the Cetacean process. In Docker, mount this as a volume for persistence across container restarts.

Path to the PEM-encoded server certificate for TLS termination. Must be paired with tls.key. Required for client certificate authentication (mTLS), optional otherwise.

Path to the PEM-encoded private key matching tls.cert.

Path to an optional TOML configuration file. All settings in this file can also be set via flags or environment variables. See Config File for the format.

Authentication provider to use. One of none (anonymous access), oidc (OpenID Connect), tailscale (Tailscale identity), cert (mTLS client certificates), or headers (trusted reverse proxy headers). Only one mode can be active at a time. See Authentication for detailed guides.

Base URL of the OpenID Connect identity provider (e.g., https://accounts.google.com or https://keycloak.example.com/realms/myorg). Must support OIDC Discovery at /.well-known/openid-configuration.

OAuth 2.0 client ID registered with the identity provider for Cetacean.

OAuth 2.0 client secret for the registered client. Use the _FILE suffix to read from a Docker secret or mounted file.

URL the identity provider redirects to after authentication (e.g., https://cetacean.example.com/auth/callback). Must use HTTPS in production; http://localhost and http://127.0.0.1 are allowed for local development.

Comma-separated list of OAuth 2.0 scopes to request from the identity provider. The defaults provide user identity, display name, and email. Add provider-specific scopes here if you need additional claims (e.g., group membership).

Hex-encoded 32-byte HMAC key used to sign browser session cookies. When unset, a random key is generated at startup — restarting the process invalidates all sessions. Set a fixed value for session persistence across restarts. Generate one with openssl rand -hex 32.

How Cetacean connects to Tailscale. local queries the host’s Tailscale daemon (requires Tailscale installed on the host). tsnet embeds a Tailscale node directly inside the process (no host-level Tailscale needed, ideal for containers). See Authentication — Tailscale for a detailed comparison.

Tailscale auth key for automatic node enrollment. Only required in tsnet mode. Generate one in the Tailscale admin console under Settings → Keys. Use the _FILE suffix to read from a Docker secret.

The hostname the embedded Tailscale node registers as on the tailnet (tsnet mode only). The dashboard will be accessible at http://cetacean.<tailnet-name>.ts.net.

Directory for persisting tsnet node state (keys, registration). Mount this as a volume in Docker to avoid re-enrolling the node on every restart.

Tailscale ACL capability key used to map tailnet users to application groups (e.g., example.com/cap/cetacean). When set, Cetacean reads group grants from Tailscale’s CapMap and populates the identity’s groups array for authorization.

Path to a PEM-encoded CA certificate bundle. Client certificates must be signed by one of the CAs in this bundle to be accepted. Supports certificate chains and multiple CAs in a single file.

Name of the HTTP header containing the authenticated user’s unique identifier (e.g., X-Remote-User). This becomes the subject in the identity and is used for authorization audience matching.

Name of the HTTP header containing the user’s display name (e.g., X-Remote-Name). Shown in the dashboard’s user badge.

Name of the HTTP header containing the user’s email address (e.g., X-Remote-Email). Used for authorization audience matching alongside the subject.

Name of the HTTP header containing the user’s group memberships as a comma-separated list (e.g., X-Remote-Groups). Groups are used for authorization audience matching.

Name of an HTTP header that must carry a shared secret for the request to be accepted. Provides an additional layer of protection beyond IP-based server.trusted_proxies — the proxy must include this header with the correct value on every request.

The expected value of the shared secret header. Required when auth.headers.secret_header is set. Use the _FILE suffix to read from a Docker secret.