Windows Setup

This guide walks through running AgentX on Windows — both the Django API + databases and the Tauri desktop client. Windows is a first-class target platform alongside Linux.

Prerequisites

Tool	Notes
Python 3.14+	From python.org or `winget install Python.Python.3.14` (matches `requires-python` in `pyproject.toml` — check there if this drifts)
uv	`powershell -c “irm https://astral.sh/uv/install.ps1
Node.js 18+	From nodejs.org or `winget install OpenJS.NodeJS.LTS`
bun	`powershell -c “irm bun.sh/install.ps1
Docker Desktop	Docker Desktop for Windows with the WSL2 backend enabled
Task	`winget install Task.Task` (or `scoop install task`)
Git	`winget install Git.Git`

For building the Tauri desktop client on Windows you also need:

Tool	Purpose
Rust (stable)	`winget install Rustlang.Rustup` then `rustup default stable`
Visual Studio Build Tools	The “Desktop development with C++” workload (MSVC linker)
WebView2 Runtime	Pre-installed on Windows 11; otherwise install the Evergreen runtime

See the Tauri Windows prerequisites for the authoritative list.

First-time setup

Use PowerShell (or Windows Terminal) from the repository root:

# 1. Clone
git clone https://github.com/yourusername/agentx-source.git
cd agentx-source

# 2. Install deps + create data dirs + verify env
task setup

# 3. Configure environment
Copy-Item .env.example .env
# Edit .env — at minimum set NEO4J_PASSWORD and POSTGRES_PASSWORD

# 4. Start the database services (Docker Desktop must be running)
task db:up

# 5. Run the full stack (API + client)
task dev

task dev:web runs the client in the browser (port 1420) without the Tauri shell — handy if you haven’t installed the Rust/MSVC toolchain yet.

GPU on Windows

AgentX installs the CPU build of torch by default on every platform, so out of the box the embedding and translation models run on the CPU regardless of AGENTX_DEVICE. AgentX runs fine that way. To use an NVIDIA GPU, run the backend somewhere a CUDA build of torch can live:

Docker Desktop (recommended). Install the NVIDIA driver on the Windows host (not inside WSL), enable GPU support in Docker Desktop → Settings → Resources → WSL Integration, and add docker-compose.gpu.yml. That overlay switches the API to the qrmadness/agentx-api:latest-gpu image (CUDA 12.8) and reserves the GPU for it.
The backend directly under WSL2. Follow the Linux steps in GPU Acceleration: export UV_NO_GROUP=cpu, then uv sync.

Installing a CUDA build into a native Windows environment with uv pip install does not stick: the next uv run re-syncs the environment to the lockfile and puts the CPU build back.

Either way, confirm it worked:

curl.exe -s localhost:12319/api/health | python -m json.tool
# look for "compute": { "device": "cuda", "cuda_available": true }

See GPU Acceleration for the full device-selection reference.

Windows gotchas

Docker Desktop must be running before task db:up / task dev — the database services are containers.
Long paths / line endings: keep the repo on an NTFS drive and let Git manage line endings (git config core.autocrlf input). The translation models download ~600 MB on first run.
WSL2 file performance: if you work inside WSL2, keep the repo on the Linux filesystem (~/projects/...), not /mnt/c/..., to avoid slow I/O.
task not found: ensure the install location is on your PATH, then restart the terminal.

Once running, continue with the Quick Start.