Running Buzz (block/buzz) on Windows: setup, the two upstream bugs, and workarounds

buzz-windows.md

Running Buzz on Windows

Buzz is built for macOS. The README's quick start assumes Hermit, and Hermit is Unix only, so most of the setup has to be done by hand. Here's what actually worked for me on Windows 11 (26100), plus the failures I hit and what caused them.

Two of these are real bugs, not environment problems, and I've sent fixes upstream. The rest is local setup.

Skip Hermit

bin/ is full of Hermit shims that only run on Unix. just setup and just dev call bin/just and bin/cargo, so they can't work here. Install the toolchain yourself:

• Rust (I'm on 1.94), Node 24+, pnpm 10+, Docker Desktop, Git for Windows
• cargo install just

Then clone and install deps:

git clone https://github.com/block/buzz.git
cd buzz
cp .env.example .env
pnpm install
cargo build --workspace

Git Bash matters beyond convenience: the agent shell tool needs it, and Buzz resolves it explicitly. If you keep bash somewhere unusual, set BUZZ_SHELL.

Port collisions

docker compose up -d will fail if anything already holds Postgres 5432, MinIO 9000, or 9001. In my case another project's containers had them. Rather than stopping those, remap Buzz's in a docker-compose.override.yml:

services:
  minio:
    ports: !override
      - "9002:9000"
      - "9003:9001"
  postgres:
    ports: !override
      - "5437:5432"

The !override tag is load bearing. Without it Compose merges the port lists and you'll still collide on the original ports.

Watch out for a native Postgres service too. Mine (postgresql-x64-16) was listening on 5432, so host connections silently reached the wrong database and migrations failed with password authentication failed for user "buzz" even though the container was healthy.

Then point .env at the new ports:

DATABASE_URL=postgres://buzz:buzz_dev@localhost:5437/buzz
PGPORT=5437
BUZZ_S3_ENDPOINT=http://localhost:9002

Migrations

.env is only auto-loaded by just (set dotenv-load). Running the migrator directly means passing the variable yourself, or it quietly falls back to localhost:5432:

DATABASE_URL=postgres://buzz:buzz_dev@localhost:5437/buzz cargo run -p buzz-admin -- migrate

Seeding the local community

scripts/seed-local-community.sh needs python3. If you don't have it, the script only generates a short INSERT, so do it directly:

docker exec -e PGPASSWORD=buzz_dev buzz-postgres psql -U buzz -d buzz -c \
  "INSERT INTO communities (host) SELECT host FROM (VALUES ('localhost:3000'),('localhost'),('127.0.0.1'),('127.0.0.1:3000')) AS v(host) ON CONFLICT (lower(host)) DO NOTHING;"

Skip this and the relay fails closed with a 404 on every request, because it rejects any Host header that isn't in communities.

Running it

Relay in one shell, desktop in another:

set -a && source .env && set +a
./target/debug/buzz-relay          # ws://localhost:3000

cd desktop && pnpm exec tauri dev

Sidecar binaries need to exist before Tauri will compile, named with the target triple:

TARGET=$(rustc -vV | sed -n 's|host: ||p')
mkdir -p desktop/src-tauri/binaries
for b in buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz; do
  cp "target/debug/$b.exe" "desktop/src-tauri/binaries/$b-$TARGET.exe"
done

tauri dev won't start

'exec' is not recognized as an internal or external command
The "beforeDevCommand" terminated with a non-zero status code.

beforeDevCommand in tauri.conf.json is exec ./node_modules/.bin/vite. exec is a POSIX shell builtin and Tauri runs the script through cmd.exe on Windows. Until the fix lands, put this in desktop/tauri.win.conf.json:

{
  "build": {
    "beforeDevCommand": {
      "script": "node ./node_modules/vite/bin/vite.js --port 1420 --strictPort",
      "cwd": "..",
      "wait": false
    }
  }
}

and run pnpm exec tauri dev --config ./tauri.win.conf.json. The path is resolved relative to the working directory, not src-tauri.

Every agent dies at startup

This one cost me the most time. %APPDATA%\xyz.block.buzz.app\agents\logs\*.log:

'"node"' is not recognized as an internal or external command,
ERROR buzz_acp: agent initialize failed: Agent process exited unexpectedly
Error: all 24 agents failed to start — cannot continue

Buzz builds a PATH for agent children out of its own managed directories and the user's login-shell PATH. On Windows that login-shell PATH is deliberately skipped, because Git Bash reports POSIX paths (/c/Users/...) that would be meaningless to a native process. The comment in the source says children will inherit the real Windows PATH instead, but they don't: the spawn does command.env("PATH", path), which replaces the inherited value rather than adding to it. So the agent gets Buzz's managed directories and nothing else, and the npm .cmd shims die the moment they try to run node.

Workaround, if you don't want to patch: drop Node into a directory Buzz already puts on the agent PATH.

mkdir "$env:USERPROFILE\.local\bin"
copy "C:\Program Files\nodejs\node.exe" "$env:USERPROFILE\.local\bin"
copy "C:\Program Files\nodejs\npm.cmd"  "$env:USERPROFILE\.local\bin"
copy "C:\Program Files\nodejs\npx.cmd"  "$env:USERPROFILE\.local\bin"

You can confirm the problem by running an adapter with only that directory on PATH, which is roughly the environment the agent gets:

$env:PATH="$env:USERPROFILE\.local\bin"; codex-acp --version

Codex specifically

Even with the PATH sorted, Codex failed on its own:

Codex process has exited with code 1: The system cannot find the path specified.

codex-acp spawns whatever CODEX_PATH points at, defaulting to plain codex. If you installed Codex through npm you only have codex.cmd and codex.ps1 shims, and the adapter's spawn doesn't go through a shell, so it finds nothing. Point it at the real binary:

setx CODEX_PATH "$env:APPDATA\npm\node_modules\@openai\codex\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\bin\codex.exe"

Restart the app afterwards. setx only affects processes started later.

To check the adapter independently of Buzz, pipe it an initialize request. A healthy adapter answers with protocolVersion:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":false,"writeTextFile":false}}}}

Adapters that look installed but aren't

Buzz's in-app installer writes to NPM_CONFIG_PREFIX=%APPDATA%\Buzz\node-tools, which isn't on your PATH, so an install can appear to succeed while discovery still reports the adapter missing. Installing them normally works:

npm install -g @agentclientprotocol/claude-agent-acp
npm install -g @agentclientprotocol/codex-acp

Goose has no Windows CLI build at all. Its install command is a curl | bash script, so that harness isn't usable here regardless. Claude Code, Codex and the bundled Buzz Agent all work.

Odds and ends

• Keycloak reports unhealthy in docker compose ps. It's only needed for OAuth testing, so you can ignore it.
• The desktop app downloads about 600 MB of speech models into ~/.buzz/models on first launch. Nothing is broken, it's just slow.
• Windows draws a separate native title bar rather than the integrated one macOS gets. I sent a patch for that as well.

Upstream

• Agent PATH and beforeDevCommand: block/buzz#2506
• Integrated title bar: block/buzz#2504