Environment Variables

This page lists supported Roster environment variables and defaults.

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

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 48
printf 'Roster-1!%s\n' "$(openssl rand -base64 32 | tr -d '\n')"

Choose one model provider example, update ROSTER_AUTH_URL, replace the generated secrets, and add the provider API key.

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>

ROSTER_MODEL_PROVIDER=openai
ROSTER_MODEL_NAME=gpt-5.5
ROSTER_MODEL_EFFORT=low
OPENAI_API_KEY=<openai-api-key>

# Optional paid license.
# ROSTER_LICENSE_KEY=<license-jwt>

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=mistral
ROSTER_MODEL_NAME=mistral-large-2512
ROSTER_MODEL_EFFORT=low
MISTRAL_API_KEY=<mistral-api-key>

# Optional paid license.
# ROSTER_LICENSE_KEY=<license-jwt>

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=anthropic
ROSTER_MODEL_NAME=claude-opus-4-8
ROSTER_MODEL_EFFORT=low
ANTHROPIC_API_KEY=<anthropic-api-key>

# Optional paid license.
# ROSTER_LICENSE_KEY=<license-jwt>

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=openai
ROSTER_MODEL_NAME=openai/gpt-5.4-mini
ROSTER_MODEL_EFFORT=low
OPENAI_API_KEY=<openrouter-api-key>
OPENAI_BASE_URL=https://openrouter.ai/api/v1

# Optional paid license.
# ROSTER_LICENSE_KEY=<license-jwt>

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 /data/roster.db through ROSTER_DATA_DIR=/data	Optional SQLite file: URL override used by Roster and runtime migrations.
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.

When ROSTER_DATABASE_URL is unset, the container stores SQLite data at /data/roster.db.

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 48

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.

Provider Secret Rotation

Variable	Default	Purpose
ROSTER_PROVIDER_SECRET_KEY_ID	env:default	Identifier stored with encrypted provider credentials to support future key rotation.

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

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

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

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

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/v1
ROSTER_MODEL_PROVIDER=openai
ROSTER_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

Variable	Default	Purpose
ROSTER_LICENSE_KEY	None	Signed license JWT. If omitted, Roster runs as Free edition.
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.

CLI

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.