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 to function properly:

  • 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 somewhere safe. If you change it, all existing sessions and tokens will be invalidated.

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 and extract it:

Expand-Archive windshift-windows-x64.zip -DestinationPath .

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

WSL

If you prefer a Linux environment on Windows, install WSL 2 and use the Linux binary inside 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, you'll be prompted to create an admin account. This account has full access to all settings and workspaces.

After creating your admin account:

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

Build from Source

Requirements: Go 1.25+, Node.js 18+, npm

# Clone the repository
git clone https://github.com/windshift-io/windshift.git
cd windshift

# Build everything (frontend + backend)
make all

The make all target builds the frontend with Vite, then compiles the Go binary with the frontend embedded. The output is a single windshift binary.

For cross-platform builds:

make build-linux-x64      # Linux x86_64
make build-linux-arm64    # Linux ARM64
make build-darwin-x64     # macOS Intel
make build-darwin-arm64   # macOS Apple Silicon
make build-windows-x64    # Windows x86_64

Production builds use -ldflags "-s -w" to strip debug symbols and reduce binary size.

What's Next