Skip to main content

Build from source

Use this guide for local development or to run Windrunner from a checkout.

Requirements​

  • Git
  • Java 25
  • Maven 3.9+
  • Node.js 25+ and npm
  • PostgreSQL with pg_trgm

Prepare PostgreSQL​

Create a database and enable the extension:

createdb -h 127.0.0.1 -U postgres windrunner
psql -h 127.0.0.1 -U postgres -d windrunner \
  -c 'CREATE EXTENSION IF NOT EXISTS pg_trgm;'

Use your own PostgreSQL credentials if they differ from these examples.

Build and start​

From the repository root:

./server/build.sh
./server/start-local.sh

The build creates the frontend, packages it with the server, and produces the JAR used by the startup script. Flyway applies the schema when the server starts.

The startup defaults are:

URL:      http://localhost:8066
Database: jdbc:postgresql://127.0.0.1:5432/windrunner
Username: your operating-system username
Password: test
Login:    admin / changeme

Change the password after signing in. Override database settings with SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, and SPRING_DATASOURCE_PASSWORD.

AI provider​

The local script uses OpenAI unless configured otherwise:

export WINDRUNNER_LLM_PROVIDER=openai
export OPENAI_API_KEY=your-api-key

Gemini and Claude are also supported. Use none to run without AI:

export WINDRUNNER_LLM_PROVIDER=none

To use OpenRouter, select it explicitly and configure an OpenRouter model slug:

export WINDRUNNER_LLM_PROVIDER=openrouter
export OPENROUTER_API_KEY=your-openrouter-key
export OPENROUTER_MODEL=provider/model

To test Groq, create a GroqCloud API key and configure the provider:

export WINDRUNNER_LLM_PROVIDER=groq
export GROQ_API_KEY=your-groq-api-key
export GROQ_MODEL=openai/gpt-oss-20b

To use Ollama, start Ollama, pull a local model, and select it:

ollama pull llama3.2
export WINDRUNNER_LLM_PROVIDER=ollama
export OLLAMA_MODEL=llama3.2

Ollama uses http://localhost:11434/v1 by default. If Windrunner runs in Docker, configure OLLAMA_BASE_URL with an address reachable from the app container.

The local startup script enables voice transcription by default. The OpenAI key above can also be used for transcription. To select Gemini transcription, set the provider and its key before starting:

export WINDRUNNER_AUDIO_TRANSCRIPTION_PROVIDER=gemini
export GEMINI_TRANSCRIPTION_API_KEY=your-gemini-api-key

Set WINDRUNNER_AUDIO_TRANSCRIPTION_ENABLED=false to disable voice transcription. See Voice transcription configuration for all transcription settings.

See Configuration for supported variables.

Common fixes​

  • JAR not found: run ./server/build.sh first.
  • Database connection failed: check PostgreSQL and the SPRING_DATASOURCE_* values.
  • Missing AI key: set the key for the selected provider or use none.
  • Port in use: stop the process using port 8066.