Quick Start

Get Windshift running locally in under 5 minutes.

Container installer for macOS and Linux

If Docker or Podman is installed, use the website installer for a local SQLite instance:

curl -fsSL https://windshift.sh/install.sh | sh

The script checks Podman first and falls back to Docker. It also checks OpenSSL, generates and stores SSO_SECRET, pulls the current Windshift image, and starts the server. It uses a container volume for the database by default. You can enter a host directory when the script asks for one.

The image runs as an unprivileged user. Podman can run it without root privileges.

This installer is for local evaluation. It uses http://localhost:8080 and the latest image tag. Set WINDSHIFT_VERSION to pin another tag. Set WINDSHIFT_CONTAINER_RUNTIME=podman to require Podman. Complete the production-ready self-hosting checklist before you expose the instance to other users.

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.

Before you expose Windshift to other users, complete the production-ready self-hosting checklist.

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

Windows on ARM: Windshift 0.8.5 and later include a native Windows arm64 archive. Use that archive on Snapdragon devices and Windows virtual machines on Apple Silicon.

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