Skip to content

Configuration

Open as Markdown

SuperWitness reads its settings from environment variables; five of them point to secret files instead of putting secrets in the environment itself. Under systemd they come from /etc/superwitness/env (Install). We keep the full table here so you can answer “what does this process actually depend on?” in one place. Leading and trailing spaces are trimmed from every value.

“Normal” is serve reading real sources; “fake” is serve with SW_FAKE_SOURCES=1.

Variable Required (normal / fake) Default Meaning
SW_LISTEN no / no :8790; in fake mode 127.0.0.1:8790 the address serve binds. In fake mode it must be a loopback address.
SW_PUBLIC_URL yes / no in fake mode http:// + SW_LISTEN the address callers reach SuperWitness at. Caller tokens must carry it as their audience.
SW_DATABASE_URL yes / yes none the Postgres DSN for the runtime role.
SW_MIGRATE_DATABASE_URL no / no SW_DATABASE_URL the Postgres DSN migrations run over: the owner role.
SW_SUPERPIPELINE_URL yes / no none SuperPipeline, where runs, cards, gates and usage are read.
SW_HUB_URL yes / no none the AgentPod hub: attempts, principals, the service token, and, without the plane, the issuer of caller tokens.
SW_SUPERPIPELINE_AUDIENCE no / no SW_SUPERPIPELINE_URL exact registered HTTPS resource for the plane service token; preserves trailing slashes.
SW_HUB_AUDIENCE no / no SW_HUB_URL exact registered HTTPS resource for the plane service token; preserves trailing slashes.
SW_HUB_CLIENT_ID yes / no none SuperWitness’s AgentPod service credential id, svc_….
SW_HUB_CLIENT_SECRET_FILE yes / no none a file holding that credential’s secret.
SW_ORG_PLANE_ISSUER no / no none: the hub issues every token the organization plane’s issuer, compared exactly with each token’s iss (no trailing slash). Setting it switches caller tokens, browser sign-in and SuperWitness’s own service tokens to the plane; nothing accepts both.
SW_ORG_PLANE_JWKS_URL with the plane none the plane’s key set. Keys are cached for at most 10 minutes, refetched on an unknown kid, and the last good set is used while the plane is unreachable.
SW_ORG_PLANE_URL with the plane none the plane’s base URL, for sign-in (/api/auth/oauth2/*) and service tokens (/api/token/service).
SW_ORG_PLANE_SERVICE_CREDENTIAL_FILE with the plane (not in fake mode) none a file holding SuperWitness’s plane service credential, svc_<id>:<secret>, on one line; not readable by group or others. Under the plane, SW_HUB_CLIENT_ID and SW_HUB_CLIENT_SECRET_FILE are not used.
SW_TRACES_URL yes / no none VictoriaTraces.
SW_TRACES_TOKEN_FILE no / no none a file holding a bearer token to send to VictoriaTraces.
SW_LOGS_URL yes / no none VictoriaLogs.
SW_LOGS_TOKEN_FILE no / no none a file holding a bearer token to send to VictoriaLogs.
SW_RUN_SOURCES no / no none: nobody may report runs the run reporters, as prn_<id>=<source>,…. Each service principal named may POST /v1/runs for its one source (Run registry API).
SW_ALLOWED_PRINCIPALS no / no none: the app is off comma-separated prn_ ids who may sign in to the app (The app).
SW_APP_CLIENT_ID when the app is on none the AgentPod OAuth client browsers sign in through.
SW_SESSION_SECRET_FILE when the app is on none a file of at least 32 random bytes that keys the sign-in cookie; it must not be readable by group or others.
SW_TRUSTED_PROXIES no / no this host’s own addresses IP addresses or CIDR prefixes whose CF-Connecting-IP header is believed.
SW_SOURCE_TIMEOUT no / no 2s how long each source has to answer, as a Go duration such as 2s or 1500ms; it must be positive.
SW_OTLP_ENDPOINT no / no none: SuperWitness sends no telemetry of its own the OTLP/HTTP endpoint for SuperWitness’s own traces and metrics (Sending telemetry).
SW_FAKE_SOURCES no / – false 1 or true serves the built-in development run and accepts development tokens (Install). Accepts true/false/1/0; empty is false.

With the plane, SuperWitness asks for tokens using SW_HUB_AUDIENCE and SW_SUPERPIPELINE_AUDIENCE, falling back to each product’s URL when omitted. Set the audience to the already registered resource when the API endpoint differs from that resource, for example https://hub.agentpod.dev or https://app.superpipeline.dev. The URL settings remain the fetch endpoints. These trusted operator settings do not register resources or change caller-token acceptance. A refused exchange fails without trying the endpoint as another audience. Legacy hub service-token exchange does not use these audience settings. Explicit audiences must be exact HTTPS URLs without credentials, query or fragment; whitespace is rejected and trailing slashes are preserved.

In fake mode, the product, engine and credential settings are not used: the sources are built in. A URL among them that is set is still validated. SW_OTLP_ENDPOINT and SW_SOURCE_TIMEOUT still apply.

serve checks its settings before it starts and exits 2 with a message on the first problem it finds:

  • Missing settings. Every required setting that is unset is named in one message, for example missing required settings: SW_PUBLIC_URL, SW_HUB_URL.
  • URLs. SW_PUBLIC_URL, SW_SUPERPIPELINE_URL, SW_HUB_URL, SW_TRACES_URL, SW_LOGS_URL and SW_OTLP_ENDPOINT, when set, must be absolute http or https URLs with a host. A trailing / is removed.
  • SW_SOURCE_TIMEOUT must parse as a positive duration.
  • SW_RUN_SOURCES must be comma-separated prn_<id>=<source> pairs, a source being lowercase letters, digits and -, and no principal bound twice.
  • SW_FAKE_SOURCES must parse as a boolean.
  • The app. With SW_ALLOWED_PRINCIPALS set, SW_APP_CLIENT_ID and SW_SESSION_SECRET_FILE are required, SW_PUBLIC_URL must be https (fake mode excepted), and in fake mode SW_HUB_URL is required. Each listed id must be prn_ and letters, digits, _ or -.
  • SW_TRUSTED_PROXIES must be IP addresses or CIDR prefixes.
  • Fake mode refuses a SW_LISTEN that is not loopback.

Secret files are checked as serve starts. SW_HUB_CLIENT_SECRET_FILE (or, under the plane, SW_ORG_PLANE_SERVICE_CREDENTIAL_FILE), SW_TRACES_TOKEN_FILE, SW_LOGS_TOKEN_FILE and SW_SESSION_SECRET_FILE must each hold a non-empty value (surrounding whitespace is trimmed; the session secret must hold at least 32 bytes, and the plane credential must be one line of the form svc_<id>:<secret>) and must not be readable by group or others; otherwise serve exits 1 naming the file.

  • superwitness migrate reads only SW_MIGRATE_DATABASE_URL, else SW_DATABASE_URL, and exits 2 if neither is set.
  • superwitness rubric-add needs SW_DATABASE_URL, and migrates first over SW_MIGRATE_DATABASE_URL when that is set.
  • superwitness canary reads its own settings: the canary-only SWC_* names and a few SW_* ones it shares with the service (The canary).

That separation lets you audit the long-running service, one-off migrations, rubric changes and the live canary without assuming that one command quietly reads another command’s credentials.