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 and to encrypt stored SSO, SCM, and LLM credentials. 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 once and save the output:

openssl rand -hex 32

Start Windshift with both values set, reusing that same secret on every start:

export SSO_SECRET=<the value you generated above>
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, and any stored SSO, SCM, and LLM credentials can no longer be decrypted — you have to re-enter them.

Confirm it started

# Readiness: the process is serving and the database is reachable.
curl http://localhost:8080/readyz
# {"status":"ready","database":"ok"}

# Which build is running.
curl http://localhost:8080/api/version

# Whether the first-run setup assistant is still pending.
curl http://localhost:8080/api/setup/status

See Verify the deployment for the container equivalents.

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.4'
Expand-Archive "windshift-v$version-windows-amd64.zip" -DestinationPath .
Set-Location "windshift-v$version-windows-amd64"

Windows on ARM: Releases currently ship an x86-64 build only. On a Snapdragon device or a Windows VM on Apple Silicon, it runs under Windows' x64 emulation. For a native binary, build from source with make build-windows-arm64.

Generate an SSO_SECRET once and persist it for your user account, so every later start reuses the same value:

$bytes = New-Object byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$secret = ($bytes | ForEach-Object { $_.ToString('x2') }) -join ''
[Environment]::SetEnvironmentVariable('SSO_SECRET', $secret, 'User')
$env:SSO_SECRET = $secret

Then set the base URL and run:

$env:BASE_URL = "http://localhost:8080"
.\windshift.exe

New shells pick up the persisted SSO_SECRET automatically, so later starts need only $env:BASE_URL and .\windshift.exe.

Do not generate the secret with Get-Random. It is backed by a non-cryptographic pseudo-random generator, so the result is far more predictable than its length suggests. Use RandomNumberGenerator as shown above.

Script execution policy: Windows blocks .ps1 files by default. If you put these commands in a startup script and see "running scripts is disabled on this system", either allow local scripts for your user with Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned, or run the script once with powershell -ExecutionPolicy Bypass -File .\startup.ps1. A script copied in from a network share or shared folder may also need Unblock-File .\startup.ps1.

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.

To build a Docker image from the same checkout, including the version metadata reported by /api/version, see Build the image from source.

What's Next