Environment Variables

This page is the environment-variable reference for self-hosted Windshift. Most values have CLI flag equivalents in Configuration Options.

Required values

Variable	Required?	Description
`SSO_SECRET`	Yes	Session-cookie and SSO-state signing/encryption secret. Generate once with `openssl rand -hex 32` and keep it stable.
`BASE_URL`	Strongly recommended	Public URL users access Windshift from. Required for correct links, SSO redirects, WebAuthn, calendar feeds, and runners.

SESSION_SECRET is accepted as a legacy fallback when SSO_SECRET is not set, but new deployments should use SSO_SECRET.

HTTP and reverse proxy

Variable	Default	Description
`PORT`	`8080`	HTTP server port inside the container/process.
`BASE_URL`	-	Public URL, for example `https://windshift.example.com` or `https://example.com/windshift`.
`CONTEXT_PATH`	-	Optional subpath such as `/windshift` when serving below a domain root.
`ALLOWED_HOSTS`	-	Comma-separated accepted hostnames. Set this in production.
`USE_PROXY`	`false`	Trust forwarded protocol/client-IP headers from reverse proxies.
`ADDITIONAL_PROXIES`	-	Additional trusted proxy IPs, comma-separated.
`DISABLE_IP_RATE_LIMIT`	`false`	Disable IP-based rate limiting. Use only behind trusted controls.

When USE_PROXY=true, ensure Windshift is reachable only from your reverse proxy. Forwarded headers are security-sensitive.

Secrets, auth, and WebAuthn

Variable	Default	Description
`SSO_SECRET`	required	Preferred session and SSO secret.
`SESSION_SECRET`	-	Legacy fallback if `SSO_SECRET` is unset.
`ENABLE_ADMIN_FALLBACK`	`false`	Enable password-based admin fallback when SSO is restrictive or unavailable.
`RECOVER_USER`	-	Emergency recovery helper for user access flows.
`WEBAUTHN_RP_ID`	host name	WebAuthn relying-party ID, usually your public hostname.
`WEBAUTHN_RP_NAME`	`Windshift`	Display name shown by authenticators.

Database

Variable	Default	Description
`DB_PATH`	`windshift.db`	SQLite database file path.
`POSTGRES_CONNECTION_STRING`	-	PostgreSQL connection string. If set, PostgreSQL is used instead of SQLite.
`DB_TYPE`	-	Set to `postgres` to build a connection string from the `POSTGRES_*` variables.
`POSTGRES_HOST`	`postgres`	Host for generated PostgreSQL connection strings.
`POSTGRES_PORT`	`5432`	Port for generated PostgreSQL connection strings.
`POSTGRES_USER`	`windshift`	User for generated PostgreSQL connection strings.
`POSTGRES_PASSWORD`	-	Password for generated PostgreSQL connection strings.
`POSTGRES_DB`	`windshift`	Database name for generated PostgreSQL connection strings.
`MAX_READ_CONNS`	`120`	SQLite read connection pool size.
`MAX_WRITE_CONNS`	`1`	SQLite write connection pool size.

Recommended production form:

POSTGRES_CONNECTION_STRING=postgres://windshift:secret@postgres:5432/windshift?sslmode=disable

Docker Compose-friendly form:

DB_TYPE=postgres
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=windshift
POSTGRES_PASSWORD=secret
POSTGRES_DB=windshift

Files

Variable	Default	Description
`ATTACHMENT_PATH`	-	Directory for uploaded file attachments. Use a persistent volume in Docker.

SSH TUI and MCP

Variable	Default	Description
`SSH_ENABLED`	`false`	Enable the SSH TUI server.
`SSH_PORT`	`23234`	SSH server port.
`SSH_HOST`	`localhost`	SSH server bind address.
`MCP_ENABLED`	`false`	Enable the MCP server at `/mcp`.

Logging

Variable	Default	Description
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, or `error`.
`LOG_FORMAT`	`text`	`text`, `json`, or `logfmt`. Use `json` for most container log pipelines.

Plugins

Variable	Default	Description
`DISABLE_PLUGINS`	`false`	Disable the plugin system entirely.
`PLUGIN_DIR`	-	Primary plugin directory.
`PLUGIN_DIRS`	-	Additional plugin directories, comma-separated.

SSO network allowlists

Variable	Default	Description
`OIDC_ALLOWED_PRIVATE_CIDRS`	-	Private/CGNAT CIDRs that OIDC discovery, JWKS, and token requests may dial.

OIDC calls block private and non-public addresses by default. If your identity provider is private, allow only the exact subnet or host route needed:

OIDC_ALLOWED_PRIVATE_CIDRS=10.20.30.15/32

AI and LLM

Variable	Default	Description
`LLM_PROVIDERS_FILE`	-	Path to a custom LLM provider catalog JSON file.
`LLM_ALLOWED_PRIVATE_CIDRS`	-	Private/loopback/CGNAT CIDRs that LLM inference and model-list refresh calls may dial.
`AI_PROMPTS_DIR`	`/data/prompts` in Docker	Directory for custom AI prompt overrides.
`LLM_ENDPOINT`	-	Legacy/fallback OpenAI-compatible inference endpoint. Prefer AI Connections in the admin UI.

Public AI providers do not need LLM_ALLOWED_PRIVATE_CIDRS. Local and internal models do.

Examples:

# Ollama/LM Studio on the same host as the Windshift process
LLM_ALLOWED_PRIVATE_CIDRS=127.0.0.1/32,::1/128

# Docker bridge gateway on many Linux hosts
LLM_ALLOWED_PRIVATE_CIDRS=172.17.0.1/32

Then use a Local / Custom AI connection with a base URL such as http://localhost:11434/v1, http://host.docker.internal:11434/v1, or http://172.17.0.1:11434/v1 depending on how Windshift reaches the model server.

Coding agent runner

The coding-agent runner is optional. See Coding Agent Runner before enabling these.

Variable	Default	Description
`CODING_AGENT_RUNNER_IMAGE`	-	Enables local coding-agent runs with this runner image.
`CODING_AGENT_DOCKER_BINARY`	`docker`	Docker executable path/name.
`CODING_AGENT_WORKTREE_ROOT`	-	Host path for prepared git worktrees. Required when the runner image is set.
`CODING_AGENT_GLOBAL_CAP`	`8`	Max concurrent local agent runs.
`CODING_AGENT_WS_API_URL`	`BASE_URL`	API URL agent containers use to reach Windshift. Override when `BASE_URL` is not reachable from containers. Must end in `/api`.
`CODING_AGENT_NETWORK`	`coding-agent-egress`	Docker network used for agent containers.
`CODING_AGENT_PIDS_LIMIT`	`512`	Container PID limit.
`CODING_AGENT_MEMORY`	`4g`	Container memory and swap cap.
`CODING_AGENT_CPUS`	`2`	Container CPU cap.
`CODING_AGENT_LLM_MODEL`	-	Fallback model for agent containers. Prefer per-binding LLM connections.

Remote runner hosts use WSRUNNER_* variables in the runner process or runner container, not in the Windshift server process. See Coding Agent Runner for the supported Docker runner compose file and the full remote-runner configuration table.

Notifications, Jira, and sidecars

Variable	Default	Description
`NOTIFICATION_FLUSH_INTERVAL`	built-in	Notification write-batcher flush interval, as a Go duration (`5s`, `1m`).
`NOTIFICATION_BATCH_SIZE`	built-in	Notification write-batcher batch size.
`NOTIFICATION_SYNC_INTERVAL`	built-in	Notification synchronization interval.
`WINDSHIFT_NOTIFICATION_BATCH_INTERVAL`	built-in	Email notification batch scheduler cadence.
`JIRA_CAPTURE_PAYLOADS`	-	Directory for Jira import request/response payload debugging.
`LOGBOOK_ENDPOINT`	-	URL of a Logbook sidecar service, if used.

Docker Compose `.env` template

# Required
DOMAIN=windshift.example.com
BASE_URL=https://windshift.example.com
SSO_SECRET=replace-with-openssl-rand-hex-32

# HTTP
PORT=8080
ALLOWED_HOSTS=windshift.example.com
USE_PROXY=true

# Storage
ATTACHMENT_PATH=/data/attachments

# PostgreSQL
POSTGRES_PASSWORD=replace-with-a-strong-password
POSTGRES_CONNECTION_STRING=postgres://windshift:${POSTGRES_PASSWORD}@postgres:5432/windshift?sslmode=disable

# Traefik / ACME
LETSENCRYPT_EMAIL=admin@example.com

# Optional: local/internal LLM access
# LLM_ALLOWED_PRIVATE_CIDRS=127.0.0.1/32,::1/128
# LLM_ALLOWED_PRIVATE_CIDRS=172.17.0.1/32

Using Varlock for configuration management

Varlock is an optional CLI tool that adds schema-based validation and secret leak prevention to .env files. It works as a drop-in wrapper.

Install

# macOS
brew install dmno-dev/tap/varlock

# Linux / CI
curl -sSfL https://varlock.dev/install.sh | sh -s

Initialize

cd /path/to/windshift
varlock init

Example `.env.schema`

# @required @sensitive @type=string
SSO_SECRET=

# @required @type=url
# @example="https://windshift.example.com"
BASE_URL=

# @type=port @optional
PORT=8080

# @sensitive @optional
POSTGRES_PASSWORD=

# @optional @type=email
LETSENCRYPT_EMAIL=

# @optional
# Keep narrow. Use host routes where possible.
LLM_ALLOWED_PRIVATE_CIDRS=

Validate

varlock load

Run with validation

varlock run -- docker compose up -d