Environment Variables

This page lists environment variables for self-hosted Windshift. Most variables have CLI flag equivalents in Configuration Options.

Required values

Windshift accepts SESSION_SECRET as a legacy fallback when SSO_SECRET is unset. 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.

By default, a plain-HTTP BASE_URL works only for localhost. Any other HTTP hostname or IP fails at startup with Failed to create CORS middleware ... insecure origin patterns. Serve HTTPS instead. On a trusted LAN, set ALLOW_INSECURE_HTTP=true. See Docker for options.

Secrets, auth, and WebAuthn

The default SESSION_IP_BINDING=log records an IP change and keeps the session active. Use strict to reject a changed IP, or off to skip the comparison. Test strict with your proxy, mobile clients, and changing networks before you enforce it.

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
# `disable` is suitable only for the bundled PostgreSQL container on the same Docker network.
# Use `require`, `verify-ca`, or `verify-full` for remote or managed PostgreSQL.
POSTGRES_SSLMODE=disable

Files

SSH TUI and MCP

Logging

Outbound TLS

Keep this setting false in production. Set it to true only when every affected destination is trusted and uses a certificate that Windshift cannot verify. The setting applies to the whole process.

Plugins

Private network egress

By default, Windshift allows server-side outbound HTTP to local, loopback, and private-network addresses. To restore private-address blocking, set the variable to false:

ALLOW_LOCAL_CONNECTIONS=false

The equivalent CLI setting is:

./windshift --allow-local-connections=false

This is a global switch. When set to false, integrations cannot reach private endpoints such as a self-hosted SCM, Jira Data Center, private identity provider, local LLM server, internal webhook target, or internal SMTP server. Use network policy to keep sensitive endpoints, such as cloud metadata services and admin panels, out of reach of the Windshift host. Windshift ignores the removed OIDC_ALLOWED_PRIVATE_CIDRS and LLM_ALLOWED_PRIVATE_CIDRS variables.

See Production-ready self-hosting for normal and hardened deployment profiles.

Process memory and cache budget

The value uses MiB. It overrides --memory-limit-mb when both are set. Windshift gives the Go runtime an 80% soft heap target and gives BigCache 25% of the process budget, capped at 512 MiB. This is not a hard RSS limit. Set the container memory limit to at least the declared process budget.

Administrators can inspect the resolved budget, cache capacity, entries, hits, misses, and evictions under Admin → Diagnostics → Cache memory.

AI and LLM

Public AI providers work without extra configuration. Local and internal models, such as Ollama, LM Studio, and internal gateways, work by default. Set ALLOW_LOCAL_CONNECTIONS=false to block them.

Then create a Local / Custom AI connection. Use the base URL that Windshift can reach, such as http://localhost:11434/v1, http://host.docker.internal:11434/v1, or http://172.17.0.1:11434/v1.

Coding agent runner

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

These are the only CODING_AGENT_* settings the server reads. Agent containers run on windshift-runner hosts. Configure those hosts with WSRUNNER_* variables in the runner process, not the Windshift server process. Configure the agent image, Docker binary, worktree and cache location, and concurrency on the runner. See Coding Agent Runner for the runner Compose file and the full WSRUNNER_* 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
SESSION_IP_BINDING=log

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

# Keep certificate verification enabled. Do not set true for normal production use.
TLS_SKIP_VERIFY=false

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
# Blocks private/loopback egress for all server-side HTTP clients when set to false.
ALLOW_LOCAL_CONNECTIONS=

Validate

varlock load

Run with validation

varlock run -- docker compose up -d