All SessionFS server environment variables use the SFS_ prefix.
| Variable |
Description |
Default |
SFS_DATABASE_URL |
PostgreSQL connection URL |
sqlite+aiosqlite:///./sessionfs.db |
SFS_DATABASE_ECHO |
Log all SQL queries |
false |
SFS_DATABASE_POOL_SIZE |
Connection pool size |
20 |
SFS_DATABASE_MAX_OVERFLOW |
Extra connections beyond pool_size |
40 |
SFS_DATABASE_POOL_TIMEOUT |
Seconds to wait for a connection |
60 |
SFS_DATABASE_POOL_RECYCLE |
Recycle connections after N seconds |
1800 |
Note: Pool settings are ignored for SQLite. For asyncpg connections, use the postgresql+asyncpg:// driver prefix. If you pass postgresql://, SessionFS will auto-convert it. SSL parameters like ?sslmode=require are handled internally — asyncpg uses a proper SSL context instead of URL parameters.
| Variable |
Description |
Default |
SFS_EMAIL_PROVIDER |
Email provider: resend, smtp, none, or auto |
auto |
SFS_EMAIL_FROM |
From address for all emails |
noreply@sessionfs.dev |
SFS_RESEND_API_KEY |
Resend API key (when provider is resend or auto) |
— |
SFS_SMTP_HOST |
SMTP server hostname |
— |
SFS_SMTP_PORT |
SMTP server port |
587 |
SFS_SMTP_USERNAME |
SMTP auth username |
— |
SFS_SMTP_PASSWORD |
SMTP auth password |
— |
SFS_SMTP_TLS |
Use STARTTLS (port 587) |
true |
SFS_SMTP_SSL |
Use implicit SSL (port 465) |
false |
Auto-detection: When SFS_EMAIL_PROVIDER=auto (default), SessionFS checks:
- If
SFS_RESEND_API_KEY is set → uses Resend
- If
SFS_SMTP_HOST is set → uses SMTP
- Otherwise → logs emails without sending (no crash)
| Variable |
Description |
Default |
SFS_VERIFICATION_SECRET |
Secret for email verification JWTs AND Fernet encryption of stored API keys/tokens. Rotating this invalidates all stored judge keys and GitLab tokens. Set a random value of at least 32 characters in production; org auto-join by email domain stays off while the default is in use. |
dev-verification-secret |
SFS_REQUIRE_EMAIL_VERIFICATION |
Require email verification on signup |
true |
| Variable |
Description |
Default |
SFS_BLOB_STORE_TYPE |
Storage backend: local, s3, or gcs |
local |
SFS_BLOB_STORE_LOCAL_PATH |
Path for local blob storage |
./data/blobs |
SFS_S3_BUCKET |
S3 bucket name (no slashes — use SFS_S3_PREFIX for key prefixes) |
— |
SFS_S3_REGION |
AWS region |
us-east-1 |
SFS_S3_PREFIX |
Optional key prefix for all S3 objects (e.g. sessionfs/) |
— |
SFS_S3_ENDPOINT_URL |
Custom S3 endpoint (for MinIO) |
— |
SFS_GCS_BUCKET |
GCS bucket name |
— |
| Variable |
Description |
Default |
SFS_HOST |
Listen address |
0.0.0.0 |
SFS_PORT |
Listen port |
8000 |
SFS_LOG_LEVEL |
Log level for the API’s own logs: DEBUG, INFO, WARNING, ERROR. Applied when the process has no other logging configuration (plain uvicorn); INFO includes one timing line per session push |
INFO |
SFS_DEPLOYMENT |
self-hosted on your own install; anything else means the hosted cloud service. The session helper uses it to say whether a docs page that is cloud-only or self-hosted-only applies here. The Helm chart sets self-hosted. |
cloud |
SFS_CORS_ORIGINS |
Allowed CORS origins (comma-separated) |
— |
SFS_RATE_LIMIT_PER_MINUTE |
API rate limit per API key per minute. Set to 0 to disable |
120 |
SFS_SMTP_VERIFY_SSL |
Verify SSL certificates for SMTP. Set to false for self-signed certs |
true |
SFS_JUDGE_BASE_URL |
Custom OpenAI-compatible endpoint for LLM Judge (LiteLLM, vLLM, Ollama, etc.) |
— |
SFS_DASHBOARD_DIR |
Path to dashboard static files |
./static |
SFS_METRICS_TENANT_LABELS |
Add org_id and project_id labels (ids only, never names) to the per-tenant business metric families at /api/v1/admin/metrics. Off: those series add up across every tenant. Series grow with the number of orgs and projects when on, still capped at 10,000 per family. Helm: api.metrics.tenantLabels. See Metrics Reference. |
false |
SFS_ORG_CONCURRENCY_EXTRACTION |
How many meeting or chat extractions one organization can run at once, across every API instance. A personal project counts against its owner. 0 turns the cap off. Helm: api.limits.orgConcurrency.extraction. See Tenancy and Isolation. |
4 |
SFS_ORG_CONCURRENCY_HELPER |
How many session helper questions one organization can have running at once. Helm: api.limits.orgConcurrency.helper |
8 |
SFS_ORG_CONCURRENCY_COMPILE |
How many knowledge compiles, rebuilds and group compiles one organization can run at once. Helm: api.limits.orgConcurrency.compile |
2 |
SFS_ORG_CONCURRENCY_EXPORT |
How many CSV exports (approval log, contacts) one organization can run at once. Helm: api.limits.orgConcurrency.export |
2 |
SFS_HEAVY_READ_TIMEOUT_MS |
PostgreSQL statement timeout, in milliseconds, on the heavy read routes (search, For You, loop status and reports, spend, approval log, contacts, session changes). A cancelled read answers 503 query_timeout. 0 turns it off. Helm: api.limits.heavyReadTimeoutMs |
15000 |
| Variable |
Description |
Default |
SFS_MAX_SYNC_BYTES_FREE |
Max sync payload for free tier |
52428800 (50 MB) |
SFS_MAX_SYNC_BYTES_PAID |
Max sync payload for paid tiers (Starter/Pro/Team/Enterprise) |
314572800 (300 MB) |
SFS_MAX_SYNC_MEMBER_BYTES_FREE |
Per-member archive cap for free tier (returned as 413 SyncTooLargeError) |
10485760 (10 MB) |
SFS_MAX_SYNC_MEMBER_BYTES_PAID |
Per-member archive cap for starter / pro / team / enterprise |
52428800 (50 MB) |
SFS_RETENTION_DAYS_FREE |
Cloud retention for free tier |
14 |
| Variable |
Description |
Default |
SFS_GITHUB_APP_ID |
GitHub App ID |
— |
SFS_GITHUB_PRIVATE_KEY |
GitHub App private key (PEM contents) |
— |
SFS_GITHUB_WEBHOOK_SECRET |
Webhook HMAC-SHA256 secret (the App’s webhook secret). Required to receive GitHub webhooks: when unset, /webhooks/github refuses every delivery with 503 and logs the misconfiguration once |
— |
SFS_GITHUB_WEBHOOK_ALLOW_UNSIGNED |
Local development only. Set to 1 to accept unsigned GitHub webhooks when no secret is configured. Ignored when SFS_GITHUB_WEBHOOK_SECRET is set. Never enable in production |
unset |
SFS_GITHUB_APP_CLIENT_ID |
The GitHub App’s Client ID (not the App ID). Needed to link an installation to a SessionFS account |
— |
SFS_GITHUB_APP_CLIENT_SECRET |
The GitHub App’s client secret. Inject it from your secret manager; never put it in config files or values |
— |
SFS_GITHUB_OAUTH_CALLBACK_URL |
Required for linking: this API’s public URL + /api/v1/settings/github/oauth/callback |
— |
Linking an installation goes through a GitHub sign-in, and SessionFS accepts the link only when GitHub confirms the signed-in account can access that installation. If SFS_GITHUB_APP_CLIENT_ID, SFS_GITHUB_APP_CLIENT_SECRET, SFS_GITHUB_OAUTH_CALLBACK_URL or SFS_DASHBOARD_URL is unset, linking is disabled.
| Variable |
Description |
Default |
SFS_GITLAB_WEBHOOK_SECRET |
Global GitLab webhook token for MR events. Optional: per-user webhook secrets from Settings also work. A delivery matching neither is refused with 401 |
— |
SFS_GITLAB_ALLOW_PRIVATE_HOSTS |
Let users point the GitLab integration (PUT /api/v1/settings/gitlab) at private, loopback or plain-http hosts, for an internal self-hosted GitLab. When false the instance URL must be https and resolve to public addresses only (422 invalid_gitlab_instance_url otherwise); the host is re-checked before every outbound request and redirects are not followed. Link-local and cloud-metadata addresses are blocked in both modes. The Helm chart sets this to true (api.gitlab.allowPrivateHosts) |
false |
SFS_LLM_ALLOW_PRIVATE_HOSTS |
Let users point their own LLM endpoint (the base_url in judge settings, and on audit and narrative-summary requests) at private, loopback or plain-http hosts, for example an in-cluster Ollama, vLLM or LiteLLM. When false the URL must be https and resolve to public addresses only. The URL is checked when it is saved and again before every request; redirects are never followed, and link-local and cloud-metadata addresses are always blocked. The Helm chart sets it to true (api.llm.allowPrivateHosts). |
false |
Hosted billing configuration is SessionFS Cloud infrastructure only. Self-hosted customer deployments should not configure payment processors; enterprise licensing is handled through the SessionFS agreement and license system.
| Variable |
Description |
Default |
SFS_APP_URL |
Dashboard URL for links the server generates (invite emails, billing return pages; weekly digest links only when SFS_DASHBOARD_URL is unset and this is set explicitly) |
https://app.sessionfs.dev |
SFS_DASHBOARD_URL |
Dashboard origin for browser SSO login redirects and GitHub installation linking; also the origin of links in the weekly org activity digest. Links are left out of the digest when neither this nor an explicit SFS_APP_URL is set |
— |
SFS_API_URL |
API URL for share links and internal references |
https://api.sessionfs.dev |
SFS_PUBLIC_API_URL |
This deployment’s public API origin, e.g. https://api.sessionfs.dev. Default OIDC audience for marketplace trusted publishing. It is also the base of signup verification links; when unset they use SFS_DASHBOARD_URL (the Helm dashboard serves /api), and with neither no verification email is sent |
— |
SFS_GITLAB_OIDC_ISSUERS |
GitLab instances whose CI ID tokens may be used for marketplace trusted publishing: comma-separated https:// origins. Listed values replace the default (include https://gitlab.com to keep it); none disables GitLab. Keys are fetched only for a listed instance, from <origin>/oauth/discovery/keys, and only from a public address. An invalid entry refuses startup |
https://gitlab.com |
SFS_TRUSTED_PUBLISHING_AUDIENCE |
Overrides the OIDC audience for marketplace trusted publishing. Must be unique to the deployment: a generic value such as sessionfs refuses to start, and with neither this nor SFS_PUBLIC_API_URL trusted publishing is disabled |
SFS_PUBLIC_API_URL |
SFS_REGISTRY_POLLING_ENABLED |
Server-side polling of organization Git marketplace registries. false: the poll endpoint answers 503 and registries report server_fetch_enabled: false |
true |
SFS_REGISTRY_POLL_ALLOWED_PRIVATE_CIDRS |
Comma-separated private ranges the registry poller may reach (an internal GitLab). Loopback, link-local and metadata addresses are never reachable |
— |
SFS_REGISTRY_POLL_TIMEOUT_SECONDS |
Fetch budget of one registry poll (30-3600) |
300 |
SFS_REGISTRY_POLL_RUN_BUDGET_SECONDS |
Budget of one poll run: no new registry is claimed once elapsed + fetch budget + 300 s publish slack would exceed it (120-3000). Keep your scheduler’s timeout above budget + 120 s |
1200 |
SFS_REGISTRY_POLL_MAX_PER_ORG |
Polling-enabled registries an organization may have (more are refused with 409 poll_registry_limit) |
10 |
SFS_REGISTRY_POLL_MAX_PER_ORG_PER_RUN |
Registries of one organization polled per run, so one organization cannot starve the others |
2 |
SFS_REGISTRY_CRED_<NAME> |
A registry credential referenced as env:SFS_REGISTRY_CRED_<NAME>; requires SFS_REGISTRY_CRED_<NAME>_ORG (the one org allowed to use it) and SFS_REGISTRY_CRED_<NAME>_HOSTS (the hosts it may be sent to); optional _USERNAME |
— |
SFS_REGISTRY_SECRETS_DIR |
Mounted credential Secrets for k8s:<name> references (token, org and hosts required, optional username) |
/var/run/secrets/sessionfs/registry-credentials |
| Variable |
Description |
Default |
SFS_DEFAULT_SYNC_MODE |
Default autosync mode for new users: off, all, selective |
off |
SFS_DEFAULT_AUDIT_TRIGGER |
Default auto-audit trigger for new users: manual, on_sync, on_pr |
manual |
SFS_MAX_SYNC_BYTES_FREE |
Per-session sync cap for free tier |
52428800 (50 MB) |
SFS_MAX_SYNC_BYTES_PAID |
Per-session sync cap for paid tiers |
314572800 (300 MB) |
SFS_RETENTION_DAYS_FREE |
Session retention for free tier |
14 |
| Variable |
Description |
Default |
SFS_UPLOAD_TIMEOUT |
Seconds the CLI and daemon wait on a session upload or download (1–3600). Overrides upload_timeout under [sync] in config.toml; sfs push --timeout overrides both |
300 |
SFS_SKILL_USAGE_REPORTING |
Client-side. 0, false, off or no stops hosted-marketplace install counts from sfs skill add/remove/pull and the daemon’s reconcile. Also off whenever telemetry is off. Sent only after the one-time notice is shown by an interactive sfs skill command; 1 enables them without it |
on, after the notice |
