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, DB_REQUEST_TIMEOUT, ALLOW_LOCAL_CONNECTIONS, and WINDSHIFT_MEMORY_LIMIT_MB.
• 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, and CODING_AGENT_ENABLED.

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.

The RP ID resolves in this order: WEBAUTHN_RP_ID, then the hostname from BASE_URL, then the process host name. In a container the process host name is the container ID, which no browser will match, so set WEBAUTHN_RP_ID explicitly in containerized deployments. See WebAuthn relying-party ID in containers.

localhost is a valid RP ID. The development exception also permits WebAuthn over HTTP when the host is localhost. A single-label hostname such as windshift is not a valid RP ID for passkeys. Use a dotted hostname or localhost.

Windshift 0.8.5 and later accept values such as https://windshift.example.com:8443 for WEBAUTHN_RP_ID. Windshift stores only windshift.example.com as the protocol RP ID.

Database

Use POSTGRES_CONNECTION_STRING when possible. Use POSTGRES_* variables when Docker Compose or a secret manager makes separate values easier.

Process memory and cache budget

The environment variable wins when both forms are set. The value uses MiB.

Windshift derives two soft budgets from the process budget:

• The Go runtime receives a soft heap target equal to 80% of the process budget.
• BigCache receives 25% of the process budget, capped at 512 MiB.

The cache budget is shared by item, permission, notification, activity, and authentication caches. Cache eviction affects performance, not correctness. Windshift reloads an evicted value from persistent storage.

The Go target is not a hard RSS limit. Database allocations, goroutine stacks, memory-mapped files, and temporary request data can raise process RSS above it. Set the container memory limit to at least the Windshift process budget. Do not set a lower container limit and rely on garbage collection.

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

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.

Keep TLS_SKIP_VERIFY=false in production. If you set it to true, Windshift accepts unverified certificates for outbound HTTPS, SMTP, IMAP, and LDAP connections. This setting affects the whole process, not one integration.

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 allows server-side outbound HTTP to local, loopback, and private-network destinations. This affects SCM integrations, Jira import, LLM providers, webhooks, OIDC, and SMTP. Public endpoints work without configuration.

To restore blocking for private-address destinations, set the flag or environment variable to false:

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

ALLOW_LOCAL_CONNECTIONS=false

Keep the default when Windshift must reach an internal endpoint. Examples include self-hosted Gitea or GitHub Enterprise, Jira Data Center, a private identity provider, a local LLM gateway, and an internal SMTP server:

ALLOW_LOCAL_CONNECTIONS=true

This global switch is not a per-endpoint allowlist. It permits egress to the entire private network. If you set it to false, integrations that use local or private endpoints cannot connect. Use network policy to keep sensitive endpoints, such as cloud metadata services and admin panels, out of reach of the Windshift host.

See Production-ready self-hosting for deployment profiles and a production checklist.

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 allows LLM calls to local and private endpoints. Public provider endpoints need no extra configuration. If you set ALLOW_LOCAL_CONNECTIONS=false, local or private models, such as Ollama, LM Studio, or an internal gateway, cannot receive inference requests or model-list refreshes.

ALLOW_LOCAL_CONNECTIONS=false

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.