Quick Start

Get Windshift running locally in under 5 minutes.

Download

Download the latest binary for your platform (Linux, macOS, or Windows) from the releases page.

Run

Windshift requires two configuration values:

  • SSO_SECRET: A random key used to sign authentication tokens. Generate it once and keep it consistent across restarts.
  • BASE_URL: The URL where Windshift is accessible. Used for SSO redirects, email links, and callback URLs.

Generate your SSO secret:

openssl rand -hex 32

Start Windshift with both values set:

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

Windshift creates a SQLite database in the current directory and starts on port 8080 by default. Open http://localhost:8080 in your browser.

Tip: Save your SSO_SECRET in a secure location. If you change it, Windshift invalidates all existing sessions and tokens.

Common Startup Flags

# Change the port
./windshift --port 3000

# Specify a database path
./windshift --db /var/lib/windshift/data.db

# Use PostgreSQL instead
./windshift --postgres-connection-string "postgres://user:pass@localhost:5432/windshift"

# Enable debug logging
./windshift --log-level debug

See Configuration Options for the full list of flags.

Windows

PowerShell

Download the Windows .zip from the releases page. Replace the version below with the version in the downloaded filename. Then extract the archive:

$version = '0.8.3'
Expand-Archive "windshift-v$version-windows-amd64.zip" -DestinationPath .
Set-Location "windshift-v$version-windows-amd64"

Set the required environment variables and run:

$env:SSO_SECRET = -join ((1..32) | ForEach-Object { "{0:x2}" -f (Get-Random -Max 256) })
$env:BASE_URL = "http://localhost:8080"
.\windshift.exe

Windows SmartScreen: Release binaries are not code-signed. If Windows shows "Windows protected your PC" on first launch, confirm that you downloaded the official archive. Then select More info and Run anyway.

WSL

To use a Linux environment on Windows, install WSL 2. Then use the Linux binary in your WSL distribution:

# Inside WSL
export SSO_SECRET=$(openssl rand -hex 32)
export BASE_URL=http://localhost:8080
./windshift

Windshift running inside WSL is accessible from the Windows host at http://localhost:8080.

First Login

When you first access Windshift, it prompts you to create an admin account. This account can access all settings and workspaces.

After you create the admin account:

  1. Create a workspace: Workspaces are isolated projects with their own boards, workflows, and members.
  2. Invite team members: Add users directly or configure SSO for automatic provisioning.
  3. Set up workflows: Customize statuses and transitions for your team's process.

Build from Source

Requirements: Go 1.26.5, Node.js 24.18.0, npm 11.16.0

# Clone the repository
git clone https://github.com/Windshiftapp/core.git
cd core

# Build everything (frontend + backend)
make all

The make all target builds the frontend with Vite. It then compiles the Go binary with the frontend embedded. The output is one windshift binary.

For cross-platform builds:

make build-linux      # Linux x86_64 (static, CGO disabled)
make build-windows    # Windows x86_64

make build compiles a native binary for your current platform. make release runs a clean production build (clean deps frontend build). Production builds use -ldflags "-s -w" to strip debug symbols and reduce binary size.

What's Next