Environment Variables

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

Required values

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

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

A plain-http BASE_URL only works for localhost by default. Any other http hostname or IP fails at startup with Failed to create CORS middleware ... insecure origin patterns; serve HTTPS instead, or set ALLOW_INSECURE_HTTP=true on a trusted LAN. See Docker for the options.

Secrets, auth, and WebAuthn

Database

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

SSH TUI and MCP

Logging

Plugins

Private network egress

All server-side outbound HTTP blocks private and non-public addresses by default to reduce SSRF risk. Enable this switch when Windshift must reach internal endpoints such as a private identity provider, self-hosted SCM, or local LLM server:

ALLOW_LOCAL_CONNECTIONS=true

It is a global switch, so only enable it when sensitive internal endpoints (cloud metadata services, admin panels) are not reachable from the Windshift host. The per-endpoint variables OIDC_ALLOWED_PRIVATE_CIDRS and LLM_ALLOWED_PRIVATE_CIDRS from earlier releases have been removed and are ignored.

AI and LLM

Public AI providers work without extra configuration. Local and internal models (Ollama, LM Studio, internal gateways) require ALLOW_LOCAL_CONNECTIONS=true, see above.

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 opt-in. See Coding Agent Runner before enabling these.

These two variables are the only CODING_AGENT_* settings the server reads. Agent containers run on windshift-runner hosts, which are configured with WSRUNNER_* variables in the runner process, not in the Windshift server process. The agent image, Docker binary, worktree/cache location, and concurrency are all runner-side settings. See Coding Agent Runner for the runner compose file and the full WSRUNNER_* configuration table.

Notifications, Jira, and sidecars

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: allow egress to private/loopback endpoints (local LLM, internal IdP/SCM)
# ALLOW_LOCAL_CONNECTIONS=true

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 @type=boolean
# Opens private/loopback egress for all server-side HTTP clients.
ALLOW_LOCAL_CONNECTIONS=

Validate

varlock load

Run with validation

varlock run -- docker compose up -d