Environment Variables

Complete reference of all environment variables supported by Windshift. These can also be set via CLI flags - see Configuration Options for the flag equivalents.

Core

Variable	Default	Description
`PORT`	`8080`	HTTP server port
`BASE_URL`	-	Public URL for Windshift (used in emails, SSO redirects)
`SSO_SECRET`	-	Secret key for SSO state and session cookie encryption (generate with `openssl rand -hex 32`)

Database

Variable	Default	Description
`DB_PATH`	`windshift.db`	SQLite database file path
`DB_TYPE`	-	Database type override
`POSTGRES_CONNECTION_STRING`	-	PostgreSQL connection string (overrides SQLite)
`MAX_READ_CONNS`	`120`	Maximum SQLite read connections
`MAX_WRITE_CONNS`	`1`	Maximum SQLite write connections

Files

Variable	Default	Description
`ATTACHMENT_PATH`	-	Directory for uploaded file attachments

Proxy & Security

Variable	Default	Description
`USE_PROXY`	`false`	Trust reverse proxy headers (X-Forwarded-Proto, X-Forwarded-For)
`ALLOWED_HOSTS`	-	Comma-separated list of valid hostnames for request validation
`ADDITIONAL_PROXIES`	-	Additional trusted proxy IP addresses beyond the default private ranges

SSH / TUI

Variable	Default	Description
`SSH_ENABLED`	`false`	Enable SSH TUI server
`SSH_PORT`	`23234`	SSH server port
`SSH_HOST`	`localhost`	SSH server bind address

Logging

Variable	Default	Description
`LOG_LEVEL`	`info`	Log level: `debug`, `info`, `warn`, `error`
`LOG_FORMAT`	`text`	Log format: `text`, `json`, `logfmt`

Plugins

Variable	Default	Description
`DISABLE_PLUGINS`	`false`	Disable the plugin system entirely

Authentication

Variable	Default	Description
`ENABLE_ADMIN_FALLBACK`	`false`	Enable password-based admin login when SSO is the only auth method

AI & Services

Variable	Default	Description
`LLM_ENDPOINT`	-	URL for the LLM inference service
`LLM_PROVIDERS_FILE`	-	Path to a custom LLM providers JSON configuration
`AI_PROMPTS_DIR`	`/data/prompts` (Docker)	Directory for custom AI prompt overrides
`LOGBOOK_ENDPOINT`	-	URL for the Logbook knowledge management service

Docker Compose Template

A typical .env file for Docker Compose:

# Required
DOMAIN=windshift.example.com
PORT=8080
SSO_SECRET=your-generated-secret-here

# PostgreSQL (only if using PostgreSQL)
POSTGRES_PASSWORD=secure-database-password

# Traefik (only if using Traefik for HTTPS)
LETSENCRYPT_EMAIL=admin@example.com

# LLM (only if using local LLM inference)
LLM_THREADS=4

Using Varlock for Configuration Management

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

Install

# macOS
brew install dmno-dev/tap/varlock

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

Initialize

Run varlock init in your project directory. It reads your existing .env files and generates a .env.schema:

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=

The decorators (@required, @sensitive, @type) document each variable's constraints. Varlock uses them to catch misconfigurations before your services start.

Validate

Check your configuration without starting anything:

varlock load

This reports missing required variables, type mismatches, and other schema violations.

Run with Validation

Validate and inject variables in one step:

varlock run -- docker compose up -d

This ensures every required variable is set and correctly typed before Docker Compose starts.