Configuration
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.
Settings
Section titled “Settings”“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.
Validation
Section titled “Validation”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_URLandSW_OTLP_ENDPOINT, when set, must be absolutehttporhttpsURLs with a host. A trailing/is removed. SW_SOURCE_TIMEOUTmust parse as a positive duration.SW_RUN_SOURCESmust be comma-separatedprn_<id>=<source>pairs, a source being lowercase letters, digits and-, and no principal bound twice.SW_FAKE_SOURCESmust parse as a boolean.- The app. With
SW_ALLOWED_PRINCIPALSset,SW_APP_CLIENT_IDandSW_SESSION_SECRET_FILEare required,SW_PUBLIC_URLmust behttps(fake mode excepted), and in fake modeSW_HUB_URLis required. Each listed id must beprn_and letters, digits,_or-. SW_TRUSTED_PROXIESmust be IP addresses or CIDR prefixes.- Fake mode refuses a
SW_LISTENthat 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.
Other commands
Section titled “Other commands”superwitness migratereads onlySW_MIGRATE_DATABASE_URL, elseSW_DATABASE_URL, and exits 2 if neither is set.superwitness rubric-addneedsSW_DATABASE_URL, and migrates first overSW_MIGRATE_DATABASE_URLwhen that is set.superwitness canaryreads its own settings: the canary-onlySWC_*names and a fewSW_*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.