Every SCARAB_* knob scarab-server reads, grouped by concern: durability substrate, object store, identity, forge webhooks, execution, and retention.
Server configuration
Section titled “Server configuration”scarab-server is configured entirely from the environment; crates/scarab-server/src/config.rs
is the single documented inventory of every SCARAB_* knob, validated at boot. This page describes
what each variable does. For how to set them on your machine, see
Local Development. The shipped knobs:
Core
| Variable | Purpose |
|---|---|
SCARAB_DATABASE_URL |
Postgres connection, the durability substrate; mandatory for every serving role. |
SCARAB_ADDR |
Bind address (default 0.0.0.0:8080). |
SCARAB_ROLE |
Which slice(s) this process runs: api / scheduler / executor / webhook / converged. |
SCARAB_EXECUTOR |
k8s (prod) or local (dev/CLI). |
SCARAB_NAMESPACE |
k8s namespace step Pods launch into. |
SCARAB_PUBLIC_URL |
Scarab’s public base URL, the run deep-link every forge status carries (default http://localhost:8080). |
Object store: set SCARAB_S3_BUCKET to select S3/MinIO; otherwise SCARAB_OBJECT_DIR is the fallback to a local directory (dev).
| Variable | Purpose |
|---|---|
SCARAB_S3_BUCKET |
Selects the S3/MinIO object store when set. |
SCARAB_S3_ENDPOINT |
S3 endpoint (empty = AWS). |
SCARAB_S3_REGION |
S3 region (default us-east-1). |
SCARAB_S3_ACCESS_KEY, SCARAB_S3_SECRET_KEY |
S3 credentials. |
SCARAB_OBJECT_DIR |
Local directory for the object store (dev). |
SCARAB_CAS_CONCURRENCY |
In-flight object-store round-trips per workspace-CAS leg (default 32). The legs are latency-bound, so 32 is a floor for remote storage — raise it the further away the bucket is, and lower it when blobs are large, because peak memory is roughly concurrency × largest blob. |
Security & identity
| Variable | Purpose |
|---|---|
SCARAB_MASTER_KEY |
base64 32-byte KEK for envelope encryption, required unless SCARAB_DEV_INSECURE=1. |
SCARAB_DEV_INSECURE |
1/true downgrades the strict security failures (KEK, auth) to loud boot warnings (dev only); never relaxes the Postgres requirement. |
SCARAB_OAUTH_CLIENT_ID, _CLIENT_SECRET, _AUTHORIZE_URL, _TOKEN_URL, _USERINFO_URL |
OAuth/OIDC login provider (all five together enable real authn; a partial set refuses boot). |
SCARAB_OAUTH_SCOPES |
Space-separated scopes for the authorize redirect (optional). |
SCARAB_OAUTH_ISSUER |
Optional. The provider’s OIDC issuer (iss), e.g. https://dex.example. Set it for a real OIDC issuer: the id_token is then verified (JWKS via discovery, plus iss/aud/exp/nonce) and its claims are the identity; an invalid one fails the login. Unset = plain OAuth2 (GitHub/Forgejo), where userinfo is the identity. Setting it without the five above refuses boot. |
SCARAB_OAUTH_OWNERS |
Comma-separated entries granted Owner at login (bootstrap until scoped RBAC); others log in as Viewer. An entry matches the Principal subject or a provider-verified email claim (email_verified) — unverified email never grants Owner. |
SCARAB_OIDC_ISSUER |
Enables the OIDC issuer for keyless federation. |
SCARAB_OIDC_SIGNING_KEY_FILE |
PKCS#8 RSA PEM the issuer signs with, required when the issuer is enabled. |
SCARAB_OIDC_AUDIENCE |
aud of minted per-run tokens (default scarab). |
Forge & webhooks
| Variable | Purpose |
|---|---|
SCARAB_GITHUB_APP_ID |
GitHub App id: when set, GitHub connections authenticate in App mode (credential secret is the App PEM); absent = token mode (dev). |
SCARAB_GITHUB_WEBHOOK_SECRET |
HMAC secret for /webhooks/github. |
SCARAB_FORGEJO_WEBHOOK_SECRET |
HMAC secret for /webhooks/forgejo (each forge endpoint binds its own secret). |
Execution & sources
| Variable | Purpose |
|---|---|
SCARAB_CLONE_IMAGE |
Canonical scarab-clone image a clone step runs (default ghcr.io/thulasi-ram/scarab-clone:edge, digest-pin in prod). |
SCARAB_SIDECAR_IMAGE |
Results-egress sidecar image. |
SCARAB_RESULTS_TOKEN_SECRET |
Enables the results-egress sidecar + ingest. |
SCARAB_RESULTS_API_URL |
Base URL the sidecar posts results to. |
SCARAB_STEP_TIMEOUT_SECS |
Global default step deadline (default 3600); per-step overridable via timeout:. |
SCARAB_PLACEMENT_CONFIG_FILE |
Path to the operator placement config: cluster baseline + PlacementProfile registry; a bad path/parse fails boot. |
Retention
| Variable | Purpose |
|---|---|
SCARAB_RETENTION_LOG_DAYS |
Terminal runs’ log TTL in days (default 30); metadata retained regardless. |
SCARAB_RETENTION_ARTIFACT_DAYS |
Terminal runs’ artifact TTL in days (default 90). |
SCARAB_RETENTION_WORKSPACE_DAYS |
Terminal runs’ workspace-CAS reachability TTL in days (default 14); non-terminal runs always reachable. |
Scoped, per-environment configuration is layered on top of these process-level knobs. See Secrets and Environments.