# 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](/download).

## 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:

```bash
openssl rand -hex 32
```

Start Windshift with both values set:

```bash
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

```bash
# 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](/docs/03-configuration/01-options) for the full list of flags.

## Windows

### PowerShell

Download the Windows `.zip` from the [releases page](/download) and extract it:

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

Set the required environment variables and run:

```powershell
$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](https://learn.microsoft.com/en-us/windows/wsl/install) and use the Linux binary inside your WSL distribution:

```bash
# 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](/docs/03-configuration/02-authentication) 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

```bash
# 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:

```bash
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

- [Docker Deployment](/docs/02-deployment/01-docker) - Production setup with Docker Compose
- [Authentication](/docs/03-configuration/02-authentication) - Configure SSO, LDAP, or WebAuthn
- [CLI Tool](/docs/04-cli/01-installation) - Manage tasks from the command line