Configuration
Source of Truth
The primary configuration source is app/server/core/config.py, which builds a StartupConfig from environment variables and defaults.
When documentation and behavior disagree, treat app/server/core/config.py as authoritative.
Minimum Required Settings
These are the settings you normally need first:
SAGE_DEFAULT_LLM_API_KEYSAGE_DEFAULT_LLM_API_BASE_URLSAGE_DEFAULT_LLM_MODEL_NAME
For many local runs, these three variables plus SAGE_PORT are enough.
Server and Storage
SAGE_PORTSAGE_SESSION_DIRSAGE_LOGS_DIR_PATHSAGE_AGENTS_DIRSAGE_USER_DIRSAGE_SKILL_WORKSPACE
These control where Sage writes runtime state, sessions, agents, and skill workspace data.
Database
SAGE_DB_TYPESAGE_MYSQL_HOSTSAGE_MYSQL_PORTSAGE_MYSQL_USERSAGE_MYSQL_PASSWORDSAGE_MYSQL_DATABASE
SAGE_DB_TYPE supports file, memory, and mysql.
Default Model Configuration
SAGE_DEFAULT_LLM_MAX_TOKENSSAGE_DEFAULT_LLM_TEMPERATURESAGE_DEFAULT_LLM_MAX_MODEL_LENSAGE_DEFAULT_LLM_TOP_PSAGE_DEFAULT_LLM_PRESENCE_PENALTY
Context Budget
SAGE_CONTEXT_HISTORY_RATIOSAGE_CONTEXT_ACTIVE_RATIOSAGE_CONTEXT_MAX_NEW_MESSAGE_RATIOSAGE_CONTEXT_RECENT_TURNS
Authentication and Session
SAGE_AUTH_MODESAGE_AUTH_PROVIDERSSAGE_TRUSTED_IDENTITY_PROXY_IPSSAGE_BOOTSTRAP_ADMIN_USERNAMESAGE_BOOTSTRAP_ADMIN_PASSWORDSAGE_JWT_KEYSAGE_JWT_EXPIRE_HOURSSAGE_REFRESH_TOKEN_SECRETSAGE_SESSION_SECRETSAGE_SESSION_COOKIE_NAMESAGE_SESSION_COOKIE_SECURESAGE_SESSION_COOKIE_SAME_SITESAGE_CORS_ALLOWED_ORIGINSSAGE_CORS_ALLOW_CREDENTIALSSAGE_CORS_ALLOW_METHODSSAGE_CORS_ALLOW_HEADERSSAGE_CORS_EXPOSE_HEADERSSAGE_CORS_MAX_AGESAGE_WEB_BASE_PATHSAGE_OAUTH2_CLIENTSSAGE_OAUTH2_ISSUERSAGE_OAUTH2_ACCESS_TOKEN_EXPIRES_IN
You can ignore this entire section until you enable login, external auth providers, or OAuth2 flows.
Supported deployment modes are intentionally narrowed to three values:
SAGE_AUTH_MODE=trusted_proxyUse a trusted identity proxy mode. Sage still exposes built-in local username/password login, but only for administrators. Regular business-user identity is expected to come from an upstream system and be passed through Sage by a trusted proxy.SAGE_AUTH_MODE=oauthUse upstream OAuth/OIDC login for Sage itself. Configure providers throughSAGE_AUTH_PROVIDERS.SAGE_AUTH_MODE=nativeUse Sage’s built-in username/password authentication for local password login. This is an auth mode name, not a local-development flag.
SAGE_TRUSTED_IDENTITY_PROXY_IPS accepts a comma-separated list of proxy source IPs or CIDR ranges. Its only job is to decide whether a request source can be treated as a trusted identity proxy. Sage accepts the optional X-Sage-Internal-UserId passthrough header only when the caller IP matches this allowlist, and then uses it as request user context with the default role user.
Sage keeps CORS configurable with safe defaults:
SAGE_CORS_ALLOWED_ORIGINS: comma-separated origin allowlist, default*SAGE_CORS_ALLOW_CREDENTIALS: whether browser credentials are allowed, defaultfalseSAGE_CORS_ALLOW_METHODS: comma-separated method allowlist, default*SAGE_CORS_ALLOW_HEADERS: comma-separated request-header allowlist, default*SAGE_CORS_EXPOSE_HEADERS: comma-separated response headers exposed to the browser, default emptySAGE_CORS_MAX_AGE: preflight cache TTL in seconds, default600
The default shape is public CORS with * and no browser credentials. If you enable SAGE_CORS_ALLOW_CREDENTIALS=true, wildcard origin * is rejected and you must configure explicit origins.
SAGE_BOOTSTRAP_ADMIN_USERNAME and SAGE_BOOTSTRAP_ADMIN_PASSWORD are both optional, but they now work as an explicit opt-in pair. If either one is missing, Sage will not create a bootstrap admin user during startup.
Embeddings, Search, and Object Storage
SAGE_EMBEDDING_API_KEYSAGE_EMBEDDING_BASE_URLSAGE_EMBEDDING_MODELSAGE_EMBEDDING_DIMSSAGE_ELASTICSEARCH_URLSAGE_ELASTICSEARCH_API_KEYSAGE_ELASTICSEARCH_USERNAMESAGE_ELASTICSEARCH_PASSWORDSAGE_S3_ENDPOINTSAGE_S3_ACCESS_KEYSAGE_S3_SECRET_KEYSAGE_S3_SECURESAGE_S3_BUCKET_NAMESAGE_S3_PUBLIC_BASE_URL
You only need these when you enable knowledge-base, search, embedding, or object-storage-backed features.
SAGE_EML_ENDPOINTSAGE_EML_ACCESS_KEY_IDSAGE_EML_ACCESS_KEY_SECRETSAGE_EML_SECURITY_TOKENSAGE_EML_ACCOUNT_NAMESAGE_EML_TEMPLATE_IDSAGE_EML_REGISTER_SUBJECTSAGE_EML_ADDRESS_TYPESAGE_EML_REPLY_TO_ADDRESS
Observability
SAGE_TRACE_JAEGER_ENDPOINTSAGE_TRACE_JAEGER_UI_URLSAGE_TRACE_JAEGER_PUBLIC_URLSAGE_TRACE_JAEGER_BASE_PATH
These are optional unless you actively run observability infrastructure.
Sandbox and Runtime Safety
These settings are consumed by the runtime outside the main server config object:
SAGE_SANDBOX_MODESAGE_REMOTE_PROVIDERSAGE_SANDBOX_MOUNT_PATHSSAGE_LOCAL_CPU_TIME_LIMITSAGE_LOCAL_MEMORY_LIMIT_MBSAGE_LOCAL_LINUX_ISOLATIONSAGE_LOCAL_MACOS_ISOLATIONSAGE_USE_CLAW_MODE
Most local users can start with SAGE_SANDBOX_MODE=local and leave the rest at defaults.
Frontend Environment
The web client also reads frontend-specific Vite variables:
VITE_SAGE_API_BASE_URLVITE_SAGE_WEB_BASE_PATH
Example .env
SAGE_PORT=8080
SAGE_AUTH_MODE=trusted_proxy
SAGE_DEFAULT_LLM_API_KEY=your-api-key
SAGE_DEFAULT_LLM_API_BASE_URL=https://api.deepseek.com/v1
SAGE_DEFAULT_LLM_MODEL_NAME=deepseek-chat
SAGE_DB_TYPE=file
SAGE_SESSION_DIR=sessions
SAGE_AGENTS_DIR=agents
SAGE_TRUSTED_IDENTITY_PROXY_IPS=10.0.0.0/8,127.0.0.1/32
SAGE_BOOTSTRAP_ADMIN_USERNAME=admin
SAGE_BOOTSTRAP_ADMIN_PASSWORD=change-this-before-first-run
SAGE_SANDBOX_MODE=local
OAuth deployment example:
SAGE_AUTH_MODE=oauth
SAGE_AUTH_PROVIDERS=[{"id":"corp-sso","type":"oidc","name":"Corp SSO","discovery_url":"https://sso.example.com/.well-known/openid-configuration","client_id":"sage","client_secret":"secret"}]
Native auth deployment example:
SAGE_AUTH_MODE=native
Recommendation
Start with the model variables, SAGE_PORT, and local storage directories. Add auth, database, object storage, embedding, or observability settings only when those subsystems are actually in use.