> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sengol.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Settings for SDK and CLI users, and for the appliance.

## SDK and CLI

| Variable | Used by | Meaning |
| - | - | - |
| `SENGOL_API_URL` | CLI, SDK | The appliance URL, for example `https://sengol.internal.example` |
| `SENGOL_API_TOKEN` | CLI, SDK | An `sk_` token or a session JWT |
| `SENGOL_TENANT_ID` | CLI, SDK | Must equal the appliance's tenant. A mismatch is refused with `422`. |
| `SENGOL_CONFIG` | CLI | Path to `sengol.yaml` for custom policies (default `./sengol.yaml`) |
| `SENGOL_SPOOL_DIR` | SDK | Where `ApiAuditSink` spools records (default `~/.sengol/spool`) |
| `OPENAI_API_KEY`, `JUDGE_LLM_BASE_URL` | judges | OpenAI-compatible judge credentials and endpoint |
| `ANTHROPIC_API_KEY` | judges, gate | Anthropic judge credentials |
| `SENGOL_GITHUB_OIDC_AUDIENCE` | CI | OIDC audience for GitHub Actions (default `sengol`) |
| `SENGOL_CI_OIDC_TOKEN_URL`, `SENGOL_CI_OIDC_TOKEN_AUTH` | CI | OIDC token source for other CI providers |

## Appliance

### Required

| Variable | Meaning |
| - | - |
| `SENGOL_AUDIT_URI` | PostgreSQL DSN: `postgresql+asyncpg://user:pass@host:5432/db` |
| `SENGOL_TENANT_ID` | The install's tenant label. Set once, before the first record. |
| `SENGOL_SIGNING_KEY` | HMAC signing key for records |
| `SENGOL_JWT_SIGNING_KEY` | Signs session tokens |
| `SENGOL_LICENSE_FILE` or `SENGOL_LICENSE` | Licence file path, or the token inline |

### Database roles

The API refuses to start when its database role is a superuser, can create
roles, or owns (or belongs to the owner of) the guard version tables. Migrate
as an owner role and serve as another.

| Variable | Meaning |
| - | - |
| `SENGOL_MIGRATION_AUDIT_URI` | DSN `alembic` uses. Defaults to `SENGOL_AUDIT_URI`. |
| `SENGOL_RUNTIME_DB_ROLE` | Role that `alembic` grants data access to after every upgrade. The API's `SENGOL_AUDIT_URI` logs in as this role. |
| `SENGOL_ALLOW_OWNER_RUNTIME_ROLE` | `1` lets the API run as the owner role. Development only. The shipped Docker Compose file sets it to `1`. |

### Evidence

| Variable | Meaning |
| - | - |
| `SENGOL_EVIDENCE_COUNTERSIGN` | `ed25519` (default) turns on countersigning |
| `SENGOL_EVIDENCE_SIGNING_KEY` | Ed25519 private key, PEM. Without it, the API starts and logs that countersigning is unavailable. |
| `SENGOL_EVIDENCE_ANCHOR` | `1` anchors records to a timestamp authority and transparency log |
| `SENGOL_ANCHOR_INTERVAL_SECONDS` | Anchoring interval (default `3600`) |
| `SENGOL_REPORTS_DIR` | Where Console and API reports are stored |

### Identity

| Variable | Meaning |
| - | - |
| `SENGOL_API_TOKEN_TTL_HOURS` | Lifetime of a new `sk_` token, in hours. Default 720. `0` or `none` makes new tokens non-expiring. An invalid or negative value falls back to 720. A token can ask for a shorter life at mint; it never gets a longer one. `local` auth mode only |
| `SENGOL_CONSOLE_ADMIN_SECRET` | Bootstrap secret, exchanged for a one-hour admin token |
| `SENGOL_BOOTSTRAP_ADMIN_EMAIL`, `SENGOL_BOOTSTRAP_ADMIN_PASSWORD` | Seeds the first local admin |
| `SENGOL_OIDC_PROVIDER_URL` | Turns on OIDC sign-in |
| `SENGOL_OIDC_ISSUER`, `SENGOL_OIDC_CLIENT_ID`, `SENGOL_OIDC_CLIENT_SECRET`, `SENGOL_OIDC_REDIRECT_URI` | OIDC application settings |
| `SENGOL_OIDC_CLAIM_SOURCE` | `oidc_groups` (default) or `app_role` |
| `SENGOL_OIDC_DEFAULT_ROLE` | Role for users matching no mapping (default `viewer`) |
| `SENGOL_GITHUB_OIDC_AUDIENCE` | Accept GitHub Actions OIDC tokens with this audience |
| `SENGOL_CI_OIDC_ISSUERS` | Other trusted CI OIDC issuers, comma-separated |
| `SENGOL_CI_OIDC_ALLOWED_REPOSITORIES` | From the 2026-10-07 sengol release. Repositories allowed to exchange a CI OIDC token, comma-separated: `owner/repo`, `owner/*` or a numeric project id, with an `<issuer>=` prefix for a non-GitHub issuer. Unset or empty admits no repository |
| `SENGOL_BREAK_GLASS_ENABLED`, `SENGOL_BREAK_GLASS_PASSWORD`, `SENGOL_BREAK_GLASS_MODE` | Emergency admin access when the IdP is down |
| `SENGOL_SOD_REQUIRE_STEP_UP` | `true` requires MFA for CRITICAL-tier governed steps |

### Metrics

| Variable | Meaning |
| - | - |
| `SENGOL_METRICS_TOKEN` | Bearer token Prometheus presents to `GET /metrics`. Unset or empty: `/metrics` answers `503` and serves nothing. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.