Configuration

Scopwis separates deployment configuration, server-owned product configuration, and client preferences. The public Bootstrap contract tells clients which product capabilities exist before they call protected APIs.

Core Server settings

SCOPWIS_HOST=127.0.0.1
SCOPWIS_PORT=3000
SCOPWIS_DATA_ROOT=/path/to/data
SCOPWIS_LOAD_PUBLIC_DATA=true

Use 0.0.0.0 only when you intentionally want network access and have configured authentication/origin policy.

Model configuration

Use Settings → Models or SCOPWIS_MODEL_* deployment variables. Persisted Settings configuration takes precedence once it exists.

Jev is a separate optional decision-plane assist under the Models settings. Its failure is fail-soft: an unavailable Jev configuration cannot replace deterministic completion gates or block the main reasoning path.

Authentication

SCOPWIS_AUTH_REQUIRED=false keeps a Guest workspace. When authentication is required, configure a supported OAuth/OIDC provider and make the public base URL match its callback exactly.

Clients receive only a Scopwis session. Provider OAuth access tokens and client secrets remain server-side.

Configure GitHub sign-in from Settings

1. In GitHub, create an OAuth App and keep its Client ID and Client Secret.
2. Open Settings → Account → GitHub SSO. Enable GitHub, enter the Client ID and Secret, and set the public origin of this Scopwis Server, for example https://scopwis.example.com.
3. Copy the displayed callback URL, https://scopwis.example.com/api/v1/auth/github/callback, into the OAuth App's Authorization callback URL.
4. On the first save, enter the Server's setup token. The deployment administrator sets SCOPWIS_SSO_SETUP_TOKEN in the Server environment. This token authorizes initial setup and recovery; it is not a GitHub credential.
5. Save and use Sign in with GitHub. An authenticated administrator who saves with the setup token becomes this configuration's owner and can update it later.

GitHub credentials are encrypted on the Server. The page shows whether a secret exists without returning it; leaving the Secret field empty preserves the saved value. Updates use a revision check and apply to new sign-in attempts immediately. Authorization flows already in progress retain their original configuration. HTTPS is required for a remote origin; local development can use a loopback HTTP origin.

Environment deployments can still use SCOPWIS_GITHUB_CLIENT_ID, SCOPWIS_GITHUB_CLIENT_SECRET, and SCOPWIS_PUBLIC_BASE_URL. Persisted GitHub Settings take precedence. With SCOPWIS_AUTH_REQUIRED=true, the last active sign-in provider cannot be disabled.

GitHub uses Authorization Code with S256 PKCE. See GitHub's OAuth App authorization guide.

Web origins

Cross-origin browser deployments use an explicit HTTPS origin allowlist, for example:

SCOPWIS_ALLOWED_ORIGINS=https://app.example.com

Wildcard, credential-bearing, remote plain-HTTP, and path/query-bearing origins fail closed.

Persistent data

Runtime artifacts, ownership, conversations, encrypted configuration, and source state live under SCOPWIS_DATA_ROOT. Large query payloads are stored separately from their immutable artifact envelopes and may expire under the configured query-artifact TTL.

Do not edit encrypted state files by hand. Back up the data root before destructive migration work.

Client capability negotiation

Clients call GET /api/v1/bootstrap before protected business APIs. Stable capabilities include Agent task/runtime features, analysis methods, artifacts, reports, data sources, model configuration, external capabilities, and semantics. A missing known capability should disable the corresponding UI instead of probing the endpoint and hoping for a 404.