Configuration Options

Configure Windshift with command-line flags or environment variables. Docker deployments usually use environment variables. The standalone binary can use either style. Do not set both for one setting because current releases do not use one precedence rule for every setting.

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

Current releases resolve flags and environment variables for each setting. Avoid setting both for one setting.

• Environment variable wins: PORT, DB_PATH, POSTGRES_CONNECTION_STRING, ATTACHMENT_PATH, LOG_LEVEL, LOG_FORMAT, SSH_PORT, SSH_HOST, MAX_READ_CONNS, MAX_WRITE_CONNS, MAX_USER_CONCURRENCY, POSTGRES_REPLICA_COUNT, POSTGRES_CONNECTION_HEADROOM, and DB_REQUEST_TIMEOUT.
• CLI flag wins: ALLOWED_HOSTS, BASE_URL, WINDSHIFT_CONTEXT_PATH, LLM_PROVIDERS_FILE, and AI_PROMPTS_DIR.
• Boolean settings combine: An enabled flag or a true environment variable enables the setting. A flag cannot disable a setting that its environment variable enables. This includes USE_PROXY, DISABLE_PLUGINS, SSH_ENABLED, CODING_AGENT_ENABLED, and ALLOW_LOCAL_CONNECTIONS.

Built-in defaults apply when neither source provides a value. Until releases standardize this behavior, use one configuration style for each setting.

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.

ALLOWED_HOSTS configures browser-security middleware. It does not reject requests based on their Host header. For a normal single-domain deployment, leave it unset. Windshift then derives the origin from BASE_URL. An explicit value overrides that derivation.

Plain HTTP is localhost-only by default. A BASE_URL such as http://myhost.internal:8080 fails at startup with Failed to create CORS middleware ... insecure origin patterns. Credentialed CORS refuses insecure origins other than localhost. Serve HTTPS through a reverse proxy with USE_PROXY=true, or directly with --tls-cert and --tls-key. On a trusted LAN, you can set ALLOW_INSECURE_HTTP=true. See Docker for details.

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

BASE_URL=https://example.com/windshift
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 POSTGRES_* variables when Docker Compose or a secret manager makes separate values 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

Private network egress

By default, Windshift blocks server-side outbound HTTP to private, loopback, link-local, multicast, and CGNAT destinations. This covers SCM integrations, Jira import, LLM providers, OIDC, and webhooks. Public endpoints work without configuration.

If Windshift must reach an internal endpoint, enable the switch. Examples include self-hosted Gitea or GitHub Enterprise, Jira Data Center, a private identity provider, and a local LLM gateway:

ALLOW_LOCAL_CONNECTIONS=true

This global switch is not a per-endpoint allowlist. It opens egress to the entire private network. Enable it only when network policy keeps sensitive endpoints, such as cloud metadata services and admin panels, out of reach of the Windshift host.

Earlier releases used the per-endpoint allowlists OIDC_ALLOWED_PRIVATE_CIDRS and LLM_ALLOWED_PRIVATE_CIDRS. Windshift ignores these removed variables. Use ALLOW_LOCAL_CONNECTIONS instead.

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 select a model immediately. The Refresh button can still fetch the live catalog.

Local and internal LLM endpoints

By default, Windshift protects LLM calls from SSRF. Public provider endpoints need no extra configuration. Local or private models, such as Ollama, LM Studio, or an internal gateway, require the global private-egress switch. This applies to inference requests and model-list refreshes:

ALLOW_LOCAL_CONNECTIONS=true

See Private network egress for what this switch covers.

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 a provider, change default models, or route a provider through a proxy, copy the built-in catalog. Then point Windshift to 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. In order, they are %s (today's date), %s (current user name), %d (user ID), and %d (assignee ID for "my items" lookups). Preserve all four in this order when you override the prompt.

Coding agent runner

See Coding Agent Runner for the full deployment guide.

The coding-agent system is opt-in. Enable it with --enable-coding-agent or CODING_AGENT_ENABLED=true. The Windshift server dispatches runs to windshift-runner hosts. It does not run agent containers. The server reads only these two variables:

Configure the agent image, Docker binary, worktree and cache location, concurrency, and container resource limits on the runner host. Use WSRUNNER_* variables, not Windshift server variables. See Coding Agent Runner for the runner Compose file and the full WSRUNNER_* 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

ALLOW_LOCAL_CONNECTIONS=true \
./windshift --base-url http://localhost:8080

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