Configuration Options

Windshift is configured through CLI flags and environment variables. Flags take precedence over environment variables.

Server

Database

Files & Attachments

TLS

SSH / TUI

Logging

Plugins

Authentication

AI / LLM

AI features are powered by a language model. Most deployments connect an external provider (Anthropic, OpenAI, Google Gemini, and others) from the in-app AI settings — paste an API key and pick a model. The settings below are for operators who want to customize the provider catalog, run their own model, or tune the prompts. See the user-facing AI Features guide for the admin workflow.

LLM providers file

Windshift ships with a built-in catalog of providers that appear in the AI settings out of the box:

To add providers, change the default models, or point at a different base URL, supply your own JSON file via --llm-providers / LLM_PROVIDERS_FILE. The file replaces the built-in catalog. The easiest starting point is the bundled default — copy it and edit:

internal/llm/llm_providers.json on GitHub

Each entry describes one provider and the models offered for it:

{
  "providers": [
    {
      "type": "openai",
      "name": "OpenAI",
      "api_format": "openai",
      "base_url": "https://api.openai.com",
      "models_endpoint": "/v1/models",
      "models_auth_scheme": "bearer",
      "models_response_format": "openai",
      "models": [
        { "id": "gpt-4o", "name": "GPT-4o", "max_tokens": 4096 }
      ]
    }
  ]
}

Any OpenAI-compatible endpoint works with "api_format": "openai" — set base_url to your service. You can also point Windshift at a self-hosted, OpenAI-compatible inference server with LLM_ENDPOINT instead of (or alongside) a hosted provider.

AI prompt overrides

Every AI feature uses an embedded system prompt that works out of the box. To tune the wording, tone, or instructions for a feature, place a <name>.txt file in the directory given by --ai-prompts-dir / AI_PROMPTS_DIR (the Docker image defaults this to /data/prompts). Only the files you provide are used — anything missing or empty keeps its built-in default, so you can override a single feature without touching the rest.

The current default prompts are a useful reference — copy one and edit it:

internal/llm/prompts/ on GitHub

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, or chat output will be malformed.

In Docker, mount your overrides at the prompts directory:

services:
  windshift:
    image: ghcr.io/windshiftapp/windshift:latest
    volumes:
      - ./my-prompts:/data/prompts:ro

To verify an override loaded without spending a model call, append ?preview=true to an AI feature endpoint — the response echoes the assembled system prompt instead of calling the LLM:

curl "http://localhost:8080/ai/plan-my-day?preview=true"

Examples

Minimal (SQLite)

./windshift --port 3000 --db /data/windshift.db

Production (PostgreSQL + Proxy)

./windshift \
  --port 8080 \
  --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

Development

./windshift \
  --port 8080 \
  --db dev.db \
  --log-level debug \
  --no-csrf