Configuration Options

Windshift can be configured with command-line flags and environment variables. Flags win over environment variables when both are present. The Docker image is usually configured with environment variables; the standalone binary can use either style.

Production checklist

For a self-hosted production deployment, set these first:

Generate a secret with:

openssl rand -hex 32

Keep the value. Changing SSO_SECRET invalidates existing sessions and can break encrypted SSO/provider credentials.

Configuration precedence

Windshift resolves configuration in this order:

1. Explicit CLI flag
2. Environment variable, where supported
3. Built-in default

Example:

PORT=8080 ./windshift --port 3000

Windshift listens on 3000, because the flag wins.

HTTP, proxy, and public URL

When USE_PROXY=true, Windshift trusts forwarded headers. Make sure only your reverse proxy can reach the Windshift port. Do not expose the backend port directly to the internet.

For subpath deployments, include the path in both BASE_URL and CONTEXT_PATH:

BASE_URL=https://example.com/windshift
CONTEXT_PATH=/windshift

Secrets and authentication

SSO_SECRET is required at startup. SESSION_SECRET is accepted only as a fallback for older deployments.

WebAuthn

Set BASE_URL and ALLOWED_HOSTS correctly before enabling passkeys/WebAuthn.

Database

Use POSTGRES_CONNECTION_STRING when possible; use the POSTGRES_* family when Docker Compose or secret managers make separate variables easier.

Files and attachments

In Docker, mount a persistent volume at /data and use /data/attachments.

TLS

Most deployments should terminate TLS at a reverse proxy and run Windshift over an internal network.

SSH TUI and MCP

Logging and rate limits

For container production logs, use:

LOG_FORMAT=json
LOG_LEVEL=info

Plugins

SSO and private identity providers

By default, OIDC HTTP clients block private, loopback, link-local, multicast, and CGNAT addresses to reduce SSRF risk. If your IdP is internal, allow only the exact CIDR(s) needed.

Examples:

# Internal IdP subnet
OIDC_ALLOWED_PRIVATE_CIDRS=10.20.30.0/24

# A single private IdP host
OIDC_ALLOWED_PRIVATE_CIDRS=10.20.30.15/32

AI and LLM providers

AI features are configured in the Windshift admin UI after startup. Operators can customize the provider catalog and network policy here.

Windshift's built-in provider catalog includes Anthropic, OpenAI, Google Gemini, Z.AI, OpenRouter, and Local / Custom. OpenRouter includes a seed model list so admins can pick a model immediately; the Refresh button can still fetch the live catalog.

Local and internal LLM endpoints

LLM calls are SSRF-protected by default. Public provider endpoints work without extra configuration, but local or private models require an explicit allowlist. This applies to both inference requests and model-list refreshes.

For an Ollama or LM Studio server on the same host as the Windshift process:

LLM_ALLOWED_PRIVATE_CIDRS=127.0.0.1/32,::1/128

For Windshift running in Docker and reaching a host service through Docker's bridge gateway:

LLM_ALLOWED_PRIVATE_CIDRS=172.17.0.1/32

Then create a Local / Custom AI connection in the admin UI with a base URL such as:

http://host.docker.internal:11434/v1

or:

http://172.17.0.1:11434/v1

Only allow the exact host or subnet you need. Do not allow broad ranges such as 10.0.0.0/8 unless your network policy already prevents access to sensitive services.

Custom provider catalog

To add providers, change default models, or route a provider to a proxy, copy the built-in catalog and point Windshift at your copy:

internal/llm/llm_providers.json

Minimal OpenAI-compatible provider:

{
  "providers": [
    {
      "type": "local",
      "name": "Local / Custom",
      "api_format": "openai",
      "base_url": "http://127.0.0.1:11434/v1",
      "models_endpoint": "/v1/models",
      "models_auth_scheme": "bearer",
      "models_response_format": "openai",
      "models": [
        { "id": "llama3.1:8b", "name": "Llama 3.1 8B", "max_tokens": 4096 }
      ]
    }
  ]
}

Supported api_format values are:

Provider model-refresh settings:

AI prompt overrides

Every AI feature uses an embedded system prompt. To override one prompt, place a <name>.txt file in AI_PROMPTS_DIR. Missing files keep the built-in default.

Default prompts are here:

internal/llm/prompts/

Important: ai_chat.txt contains four runtime placeholders — %s (today's date), %s (current user's name), %d (user ID), and %d (assignee ID for "my items" lookups), in that order. Preserve all four in the same order when overriding this prompt.

Coding agent runner

See Coding Agent Runner for the full deployment guide.

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

Examples

Minimal SQLite

SSO_SECRET=$(openssl rand -hex 32) \
BASE_URL=http://localhost:8080 \
./windshift --db /data/windshift.db

Production behind a reverse proxy

./windshift \
  --postgres-connection-string "postgres://windshift:secret@db:5432/windshift?sslmode=require" \
  --use-proxy \
  --allowed-hosts windshift.example.com \
  --base-url https://windshift.example.com \
  --attachment-path /data/attachments \
  --log-level info \
  --log-format json

Local LLM on the host

LLM_ALLOWED_PRIVATE_CIDRS=127.0.0.1/32,::1/128 \
./windshift --base-url http://localhost:8080

Then add a Local / Custom AI connection in the UI with http://localhost:11434/v1.