Configuration

Configuration reaches the API through the environment (ASP.NET-style Section__Key names). On the self-host stack, set them in the same .env that sits next to the compose file — the API reads it directly. The annotated reference is the env.example attached to every release; this page covers the settings that matter for a real deployment.

Identity

Identity__AcceptedCredentials declares which credential kinds the Instance accepts. Unset means the zero-config default: local credentials only — username-free local accounts with the first-user-claims-the-Instance flow. Connecting an identity provider adds to the set; it never replaces it.

Identity__AcceptedCredentials__0=Local
Identity__AcceptedCredentials__1=Oidc

Specbench brings no identity vendor of its own — connect any OIDC issuer (Keycloak, Authentik, a hosted IdP, …).

Local credential policy is tunable; the password policy is stated on the sign-up form, and lockout throttles password guessing automatically:

Identity__Local__PasswordMinimumLength=12
Identity__Local__LockoutMaxFailedAttempts=5
Identity__Local__LockoutDuration=00:15:00

Who may join, and who may create organizations

Two settings decide how people get onto the Instance. The first person to arrive always claims it and becomes its first Instance Operator, whatever these say.

# InvitationOnly (default): after the claim, people join by invitation.
# Open: anyone may become a User. Through the issuer they prove who they are;
# with local credentials they only submit an email address and a password.
Identity__RegistrationPolicy=InvitationOnly
# Anyone (default): any User may create an Organization.
# OperatorsOnly: only Instance Operators may; everyone else joins by invitation.
Identity__OrganizationCreation=Anyone

Local sign-up verifies nothing: nobody has to control the address they claim. So Open with local credentials suits evaluation and trusted networks. The Instance refuses to start with Open while both Local and Oidc are accepted: somebody could sign up locally under an address and take over the person who later signs in with it through the issuer.

Agents signing in

Agents connect to the MCP server either with a pasted Personal Access Token or by signing in: the Instance runs its own OAuth authorization server, so Claude Code, Codex, and chat-app connectors register themselves, send the person to a consent page on the web app, and trade the approval for tokens. Nothing needs configuring for that beyond the origin browsers reach the app on, which the compose stack derives from SPECBENCH_WEB_ORIGIN:

Identity__OAuth__Issuer=https://specs.example.com

Unset, the first Cors__AllowedOrigins entry is used, which the compose stack already sets from SPECBENCH_WEB_ORIGIN; with several origins listed, set the issuer explicitly. It must be https except on loopback addresses (localhost, 127.0.0.1, [::1]). Token lifetimes are tunable; access tokens renew in place under one grant per authorized client:

Identity__OAuth__AccessTokenLifetime=01:00:00
Identity__OAuth__RefreshTokenLifetime=30.00:00:00

The MCP server needs the same origin to point clients at, as SPECBENCH_WEB_ORIGIN in its environment. Sign-in through the consent page uses whatever credentials the Instance accepts, so a connected issuer needs no extra registration for this.

Source control (GitHub App)

Publishing specs into a repository runs through a GitHub App you register yourself. Leave the settings unset to keep the integration off; a partial set fails at startup, naming the missing setting.

GitHubApp__AppSlug=my-specbench-app
GitHubApp__AppId=123456
# Exactly one of:
GitHubApp__PrivateKeyPem="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GitHubApp__PrivateKeyPath=/run/secrets/github-app-key.pem

The full walkthrough — registering the App, the Setup URL that must point back at your Instance, and the key-ring caveat for multi-replica deployments — is The GitHub App.

CORS

The API allows credentialed requests only from declared origins. The compose stack sets this to the web app's origin; adjust it if the web app is served from somewhere else:

Cors__AllowedOrigins__0=https://specbench.example.com

Connection strings

On the compose stack, don't set these. The compose file derives both connection strings from SPECBENCH_POSTGRES_PASSWORD and SPECBENCH_REDIS_PASSWORD, and its own environment: entries win over the .env on a clash — so a ConnectionStrings__* line in the .env is silently ignored. To change the database credentials, set the two SPECBENCH_* password variables (on a fresh data volume — see Data) and the connection strings follow.

On Kubernetes or any custom deployment, set them directly — both are required at startup:

ConnectionStrings__Default=Host=postgres;Port=5432;Database=specbench;Username=specbench;Password=<your-password>
ConnectionStrings__Redis=redis:6379,password=<your-password>