Local development on Windows

This guide is the Windows-specific companion to Local development. It captures the extras that trip people up when running on Windows.

Prerequisites

Rust toolchain via rustup (stable channel).
Node.js ≥ 18.
pnpm: npm install -g pnpm.
Git.
Visual Studio Build Tools with the “Desktop development with C++” workload — required for the Rust linker to find link.exe.

Environment variables

Set these in the same PowerShell session that runs the backend:

Variable	Recommended value	Purpose
`VK_SHARED_API_BASE`	`"https://api.vibekanban.com"`	Required for cloud login + project sync
`DATABASE_URL`	`"sqlite:///C:/path/to/db.sqlite"`	Absolute path to the SQLite DB
`BACKEND_PORT`	`"3002"`	Backend HTTP port
`FRONTEND_PORT`	`"3000"`	Vite dev server port
`RUST_LOG`	`"info"`	Backend log level

Without VK_SHARED_API_BASE the Sign in button is disabled and project sync won’t work. After adding the variable, restart the terminal that runs the backend.

Running

Helper script
Manual (two terminals)

A PowerShell helper that loads every variable and starts both servers ships in the repo:

.\scripts\relay-test-client\Runlocal.ps1

Terminal 1 — Backend:

$env:VK_SHARED_API_BASE = "https://api.vibekanban.com"
$env:DATABASE_URL = "sqlite:///C:/path/to/dev_assets/db.v2.sqlite"
$env:BACKEND_PORT = "3002"
cargo run --bin server

Terminal 2 — Frontend:

$env:FRONTEND_PORT = "3000"
$env:BACKEND_PORT = "3002"
cd packages/local-web
pnpm run dev

Migrations

The backend runs sqlx migrate run automatically on startup. To run them by hand:

$env:DATABASE_URL = "sqlite:///C:/path/to/db.sqlite"
sqlx migrate run --source crates/db/migrations

Troubleshooting

Linker error during cargo build

Install Visual Studio Build Tools and pick Desktop development with C++.

UI is blank or returns 504 Gateway Timeout

The Vite proxy is pointing at the wrong host. On Windows, Node prefers IPv6 localhost while the backend listens on IPv4 127.0.0.1. Confirm the backend is on 3002 and that packages/local-web/vite.config.ts proxies to 127.0.0.1:3002, not localhost:3002.

"Remote client not configured" on sign-in

Local Development Deploy with Docker Compose

​Prerequisites

​Environment variables

​Running

​Migrations

​Troubleshooting

Prerequisites

Environment variables

Running

Migrations

Troubleshooting