Environment Variables
This page lists supported Roster environment variables and defaults. It also identifies reserved names when needed to prevent accidental use.
Secrets should come from your deployment secret manager. Do not commit real values to source control or bake them into a custom image.
Quick-start .env examples
Section titled “Quick-start .env examples”Run this command twice and use the two outputs for ROSTER_AUTH_SECRET and
ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY. Generate a strong, unique bootstrap
password as well:
openssl rand -base64 48printf 'Roster-1!%s\n' "$(openssl rand -base64 32 | tr -d '\n')"Choose one model-provider example, replace every placeholder with the value for the deployment, and add the provider API key. These examples rely on the documented provider defaults and include only settings needed for the selected provider.
ROSTER_BOOTSTRAP_ADMIN_PASSWORD is required only for the first start of a
fresh production database. Remove it from the deployment secrets after the
bootstrap administrator exists and login has been confirmed.
OpenAI
Section titled “OpenAI”ROSTER_AUTH_URL=<your-roster-public-url>ROSTER_AUTH_SECRET=<generated-auth-secret>ROSTER_BOOTSTRAP_ADMIN_PASSWORD=<generated-strong-password>ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=<generated-provider-secret-encryption-key>
OPENAI_API_KEY=<openai-api-key>
# Optional paid license.# ROSTER_LICENSE_KEY=<license-jwt>Mistral
Section titled “Mistral”ROSTER_AUTH_URL=<your-roster-public-url>ROSTER_AUTH_SECRET=<generated-auth-secret>ROSTER_BOOTSTRAP_ADMIN_PASSWORD=<generated-strong-password>ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=<generated-provider-secret-encryption-key>
ROSTER_MODEL_PROVIDER=mistralMISTRAL_API_KEY=<mistral-api-key>
# Optional paid license.# ROSTER_LICENSE_KEY=<license-jwt>Anthropic
Section titled “Anthropic”ROSTER_AUTH_URL=<your-roster-public-url>ROSTER_AUTH_SECRET=<generated-auth-secret>ROSTER_BOOTSTRAP_ADMIN_PASSWORD=<generated-strong-password>ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=<generated-provider-secret-encryption-key>
ROSTER_MODEL_PROVIDER=anthropicANTHROPIC_API_KEY=<anthropic-api-key>
# Optional paid license.# ROSTER_LICENSE_KEY=<license-jwt>OpenRouter
Section titled “OpenRouter”OpenRouter uses the OpenAI provider with an OpenAI-compatible base URL.
ROSTER_AUTH_URL=<your-roster-public-url>ROSTER_AUTH_SECRET=<generated-auth-secret>ROSTER_BOOTSTRAP_ADMIN_PASSWORD=<generated-strong-password>ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=<generated-provider-secret-encryption-key>
ROSTER_MODEL_PROVIDER=openaiROSTER_MODEL_NAME=openai/gpt-5.4-miniOPENAI_API_KEY=<openrouter-api-key>OPENAI_BASE_URL=https://openrouter.ai/api/v1
# Optional paid license.# ROSTER_LICENSE_KEY=<license-jwt>Runtime defaults
Section titled “Runtime defaults”The advantys/roster container sets these Roster runtime defaults:
| Variable | Default | Purpose |
|---|---|---|
ROSTER_DATA_DIR | /data | Runtime directory for SQLite data, worker journals, connector files, and state. |
ROSTER_DATABASE_URL | Unset; uses SQLite at /data/roster.db through ROSTER_DATA_DIR=/data | Runtime database URL used by Roster and startup migrations. Use a SQLite file: URL for all editions. Enterprise deployments can use a postgres:// or postgresql:// URL. |
ROSTER_DATABASE_REPLICA_URLS | Unset | Comma-separated PostgreSQL read-replica URLs. Eligible ordinary reads can use replicas; writes, transactions, authentication, and security checks use ROSTER_DATABASE_URL. Required in HA mode. |
ROSTER_DATABASE_MIGRATION_MODE | skip for production PostgreSQL; auto otherwise | Container entrypoint policy. only migrates and exits, skip starts without migrating, and auto migrates before startup. |
ROSTER_DATABASE_POOL_MAX | 10 | Maximum connections in each PostgreSQL pool, per Roster instance and database endpoint. |
ROSTER_DATABASE_CONNECTION_TIMEOUT_MS | 5000 | Maximum time to establish a PostgreSQL connection. |
ROSTER_DATABASE_IDLE_TIMEOUT_MS | 30000 | Time an unused PostgreSQL connection can remain in the pool. |
ROSTER_DATABASE_STATEMENT_TIMEOUT_MS | 30000 | Maximum PostgreSQL statement duration. |
ROSTER_DATABASE_TRANSACTION_TIMEOUT_MS | 30000 | Maximum time a PostgreSQL connection can remain idle while a transaction is open. |
ROSTER_DEPLOYMENT_MODE | standalone | Set to ha for fail-fast production PostgreSQL multi-instance validation. |
ROSTER_SQLITE_BUSY_TIMEOUT_MS | 5000 | Positive integer milliseconds SQLite waits for another connection before reporting contention. Safe write transactions can retry recognized SQLITE_BUSY* and SQLITE_LOCKED* results. |
ROSTER_AUTH_URL | http://localhost:3000 in the container | Public origin used for auth callbacks, OAuth issuer metadata, and MCP OAuth resource discovery. Set it to the externally reachable HTTPS origin before exposing Roster or connecting OAuth MCP clients. |
ROSTER_AUTH_TRUSTED_ORIGINS | None | Comma-separated extra browser origins allowed to call auth endpoints. |
Database configuration
Section titled “Database configuration”When ROSTER_DATABASE_URL is unset, the container stores SQLite data at
/data/roster.db and runs SQLite migrations before startup in the default
auto mode.
Set an explicit SQLite path with a file: URL:
ROSTER_DATABASE_URL=file:/data/roster.dbEnterprise deployments can use PostgreSQL by setting ROSTER_DATABASE_URL to a
PostgreSQL URL and providing a valid Enterprise license. Roster supports
PostgreSQL 17 and 18:
ROSTER_DATABASE_URL=postgresql://roster:<password>@postgres.internal:5432/rosterROSTER_LICENSE_KEY=<enterprise-license-jwt>Optionally configure one or more read-only PostgreSQL endpoints. Separate multiple URLs with commas:
ROSTER_DATABASE_REPLICA_URLS=postgresql://roster_reader:<password>@replica-a.internal:5432/roster,postgresql://roster_reader:<password>@replica-b.internal:5432/rosterThis setting is required for High Availability. Replication can lag, so a request immediately following a write may briefly observe older data from a read replica.
PostgreSQL database support is only available in Enterprise. If the effective edition is Free or Pro, Roster refuses to open a PostgreSQL runtime database. Use SQLite or provide a valid Enterprise license.
Migration mode
Section titled “Migration mode”ROSTER_DATABASE_MIGRATION_MODE controls the production image entrypoint:
| Value | Behavior |
|---|---|
only | Apply pending migrations and exit without starting Roster. |
skip | Start Roster without applying migrations. |
auto | Apply pending migrations and then start Roster. |
Production PostgreSQL defaults to skip; SQLite and non-production default to
auto. An explicit value always wins. For PostgreSQL, use only in one
migration-only release job and skip on every Roster instance. The migration
job should use a schema-owning credential; Roster instances should use a
separate credential limited to runtime DML. PostgreSQL migrations are
serialized with an advisory lock if two jobs overlap accidentally.
See Production database migrations for a complete rollout example.
Each Roster instance can open one pool to the primary and one to every
configured replica. Plan for up to
instance count × (1 + replica count) × ROSTER_DATABASE_POOL_MAX Roster
connections, plus capacity for migrations, monitoring, backups, and database
administration. Lower ROSTER_DATABASE_POOL_MAX when that total would exceed
the PostgreSQL service limit.
High availability
Section titled “High availability”ROSTER_DEPLOYMENT_MODE=ha requires NODE_ENV=production, PostgreSQL,
at least one ROSTER_DATABASE_REPLICA_URLS entry,
ROSTER_DATABASE_MIGRATION_MODE=skip on Roster instances, an explicit public
auth URL, and shared auth/provider-encryption secrets. Enabled local-file CSV
connectors are rejected; use S3 or SFTP.
| Variable | Default | Purpose |
|---|---|---|
ROSTER_INSTANCE_ID | Inferred | Unique job lease owner. |
ROSTER_WORKER_ENABLED | Enabled | Enables scheduled background worker processing. |
ROSTER_WORKER_POLL_MS | 60000 | Interval for polling for scheduled work. |
ROSTER_WORKER_LEASE_MS | 120000 | Job lease duration. |
ROSTER_WORKER_HEARTBEAT_MS | 30000 | Heartbeat interval; less than half the lease duration. |
ROSTER_WORKER_MAX_ATTEMPTS | 5 | Maximum claims before terminal failure. |
ROSTER_WORKER_CONCURRENCY | 1 | Concurrent worker slots per Roster instance. |
ROSTER_WORKER_SHUTDOWN_GRACE_MS | 30000 | Graceful wait for in-flight work on shutdown. |
Workers are enabled by default. Disable them only when another Roster worker group processes scheduled work, and keep at least one worker enabled for every deployment.
Use /health/live for liveness and /health/ready for load-balancer routing.
Both probes are unauthenticated, sanitized, and excluded from rate limiting.
See High Availability for the Roster and
PostgreSQL cluster architecture.
Observability
Section titled “Observability”OpenTelemetry export is disabled by default and available in Enterprise. Free and Pro retain stdout logs, probes, and trace correlation but do not send external telemetry.
| Variable | Default | Purpose |
|---|---|---|
ROSTER_OBSERVABILITY_ENABLED | false | Enable Enterprise OTLP trace and metric export with true, 1, or yes. |
ROSTER_OBSERVABILITY_DASHBOARD_URL | None | Optional HTTP(S) link shown on the admin System health page. Credential-bearing URLs are rejected. |
OTEL_EXPORTER_OTLP_ENDPOINT | Standard local OTLP endpoint | Generic OTLP endpoint; signal-specific endpoints take precedence. |
OTEL_EXPORTER_OTLP_PROTOCOL | http/protobuf | Use http/protobuf or grpc; signal-specific protocols take precedence. |
OTEL_EXPORTER_OTLP_HEADERS | None | Standard exporter headers; keep credentials in a secret manager. |
OTEL_SERVICE_NAME | roster-platform | OpenTelemetry service name. |
OTEL_RESOURCE_ATTRIBUTES | None | Operator-owned standard resource attributes. |
OTEL_TRACES_SAMPLER | parentbased_traceidratio | Standard OpenTelemetry trace sampler. |
OTEL_TRACES_SAMPLER_ARG | 0.1 | Default 10% trace sampling ratio. |
OTEL_METRIC_EXPORT_INTERVAL | 60000 | Metric export interval in milliseconds. |
The standard signal-specific endpoint, protocol, and header variables are also supported. See Telemetry for privacy, status, Collector, and production integration guidance.
Required secrets
Section titled “Required secrets”| Variable | Default | Purpose |
|---|---|---|
ROSTER_AUTH_SECRET | None | Required secret for signed auth state and encrypted platform settings. |
ROSTER_BOOTSTRAP_ADMIN_PASSWORD | None | Required only when a production database has no bootstrap administrator. It is not needed after the bootstrap account exists. |
ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY | None | Required secret for encrypted connector and provider credentials. |
Use separate high-entropy values and keep them stable across container
restarts. Changing ROSTER_AUTH_SECRET invalidates sessions. Changing
ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY can prevent encrypted settings and
provider credentials from decrypting.
Run this command to generate a compatible 48-byte random base64 value:
openssl rand -base64 48Bootstrap password change
Section titled “Bootstrap password change”| Variable | Default | Purpose |
|---|---|---|
ROSTER_BOOTSTRAP_ADMIN_PASSWORD_CHANGE_MODE | remind | Controls a pending bootstrap administrator password change. remind allows Skip for now for the current browser session, required blocks protected actions until the password is changed, and off hides the prompt. |
MCP and OAuth
Section titled “MCP and OAuth”| Variable | Default | Purpose |
|---|---|---|
ROSTER_MCP_AUTH_MODE | api_key,oauth | MCP authentication mode. Supported values are api_key, oauth, api_key,oauth, and local-only none. |
ROSTER_OAUTH_DYNAMIC_CLIENT_REGISTRATION | Disabled in the container | Exposes OAuth Dynamic Client Registration for MCP clients. Registration still requires a Roster browser session unless the separate unauthenticated override is enabled. |
ROSTER_OAUTH_UNAUTHENTICATED_CLIENT_REGISTRATION | Disabled in the container | Allows a self-registering MCP client to call Dynamic Client Registration without a Roster session. Enable only for a restricted setup window, then disable it. |
ROSTER_OAUTH_ACCESS_TOKEN_TTL_SECONDS | 3600 | OAuth access-token lifetime. |
ROSTER_OAUTH_REFRESH_TOKEN_TTL_SECONDS | 7776000 | OAuth refresh-token lifetime, 90 days. |
ROSTER_OAUTH_AUTH_CODE_TTL_SECONDS | 600 | OAuth authorization-code lifetime. |
Roster derives the MCP OAuth resource URI automatically as
${ROSTER_AUTH_URL}/mcp.
Self-registering clients require both registration variables during their controlled setup window. Pre-registered clients require neither. See the Claude setup guide for the safe onboarding sequence.
Reserved provider-secret key identifier
Section titled “Reserved provider-secret key identifier”The provider-secret schema includes a key_id field for future encryption-key
rotation. ROSTER_PROVIDER_SECRET_KEY_ID is reserved for that work, but Roster
does not read the variable and setting it has no runtime effect. Leave it unset
unless a later release explicitly enables and documents key rotation.
Model runtime
Section titled “Model runtime”Roster runs one resolver model provider at a time. The provider value is only
the provider family; the API is selected separately by ROSTER_MODEL_API when
you need to override the provider default.
| Variable | Default | Purpose |
|---|---|---|
ROSTER_MODEL_PROVIDER | openai | Resolver model provider. Supported values are openai, mistral, and anthropic. |
ROSTER_MODEL_API | Provider default | Optional API selector. Defaults are listed below. |
ROSTER_MODEL_NAME | Provider default | Resolver model ID. Defaults are listed below. |
ROSTER_MODEL_EFFORT | low | Effort value accepted by the runtime. Supported values are none, minimal, low, medium, high, xhigh, and max. |
OpenAI
Section titled “OpenAI”| Variable | Default | Purpose |
|---|---|---|
OPENAI_API_KEY | None | Required when ROSTER_MODEL_PROVIDER=openai. |
OPENAI_BASE_URL | OpenAI SDK default endpoint | Optional OpenAI-compatible API base URL. Set only for a provider proxy, regional endpoint, or approved gateway. |
ROSTER_MODEL_API | responses | Default API for the OpenAI provider. |
ROSTER_MODEL_NAME | gpt-5.5 | Default OpenAI model. |
ROSTER_MODEL_OPENAI_RESPONSES_MAX_OUTPUT_TOKENS | Unset for direct OpenAI; 2048 for non-default OpenAI-compatible gateways | Optional positive integer sent as max_output_tokens for OpenAI Responses requests. |
Mistral
Section titled “Mistral”| Variable | Default | Purpose |
|---|---|---|
MISTRAL_API_KEY | None | Required when ROSTER_MODEL_PROVIDER=mistral. |
MISTRAL_BASE_URL | Mistral SDK default endpoint | Optional Mistral API base URL. Set only for a provider proxy, regional endpoint, or approved gateway. |
ROSTER_MODEL_API | chat-completions | Default API for the Mistral provider. |
ROSTER_MODEL_NAME | mistral-large-2512 | Default Mistral model. |
Anthropic
Section titled “Anthropic”| Variable | Default | Purpose |
|---|---|---|
ANTHROPIC_API_KEY | None | Required when ROSTER_MODEL_PROVIDER=anthropic. |
ANTHROPIC_BASE_URL | Anthropic SDK default endpoint | Optional Anthropic API base URL. Set only for a provider proxy, regional endpoint, or approved gateway. |
ROSTER_MODEL_API | messages | Default API for the Anthropic provider. |
ROSTER_MODEL_NAME | claude-opus-4-8 | Default Anthropic model. |
OpenRouter
Section titled “OpenRouter”OpenRouter uses the OpenAI provider because it exposes an OpenAI-compatible gateway:
OPENAI_API_KEY=<openrouter-api-key>OPENAI_BASE_URL=https://openrouter.ai/api/v1ROSTER_MODEL_PROVIDER=openaiROSTER_MODEL_NAME=<openrouter-model-id>When OPENAI_BASE_URL points to a non-default OpenAI-compatible gateway, Roster
defaults ROSTER_MODEL_OPENAI_RESPONSES_MAX_OUTPUT_TOKENS to 2048.
Licensing
Section titled “Licensing”| Variable | Default | Purpose |
|---|---|---|
ROSTER_LICENSE_KEY | None | Signed license JWT. If omitted, Roster runs as Free edition. Required for Pro, Enterprise, and Enterprise-only PostgreSQL database support. |
ROSTER_LICENSE_FILE | None | Path to a mounted file containing the signed license JWT. |
ROSTER_LICENSE_JWKS_FILE | /app/roster-license-jwks.json | Optional local JWKS/public keyring override for offline paid-license verification. |
The Roster CLI also supports these environment variables:
| Variable | Default | Purpose |
|---|---|---|
ROSTER_HOME | ~/.roster | CLI profile and OAuth credential storage directory. |
ROSTER_MCP_URL | None | MCP endpoint used when --mcp-url is not provided and no selected profile supplies one. |
ROSTER_API_KEY | None | API-key bearer token used when --api-key is not provided. Takes precedence over saved OAuth profile credentials. |