← Docs

Run an agent on Windows

Windows uses Docker Desktop (WSL2 backend) for the agent container and Ollama for Windows for the model — Ollama runs natively and uses your NVIDIA GPU directly, so there's no container-GPU setup to do.

Prerequisites

1. NVIDIA GPU driver

A recent NVIDIA driver (GeForce/Studio). Get it from nvidia.com/drivers. Verify in a terminal:

nvidia-smi

You should see your GPU and its memory. No CUDA toolkit needed — Ollama bundles what it uses.

2. Ollama for Windows

Download and install from ollama.com/download/windows. It installs a background service on http://localhost:11434 and uses your GPU automatically. Verify:

ollama --version
ollama run qwen2.5-coder:7b "say hello"   # first run pulls the model

See choosing a model for what fits your VRAM.

3. Docker Desktop

Install from docker.com/products/docker-desktop (keep the default WSL2 backend). Verify:

docker --version

Create your agent

In app.keikaku.ai → Agents → New agent. You'll get a docker run command with your connection token already filled in. It looks like this (the app supplies the real AGENT_TOKEN):

docker run -d --name keikaku-agent --label com.docker.compose.project=keikaku --restart unless-stopped ^
  -e API_BASE_URL=https://api.keikaku.ai ^
  -e AGENT_TOKEN=<from the app> ^
  -e OLLAMA_URL=http://host.docker.internal:11434 ^
  -e MODEL=qwen2.5-coder:7b ^
  -p 9170:9170 ^
  ghcr.io/keikaku-ai/agent:latest

Verify it connected

Two ways: the agent appears as online in the app under Agents, and the local dashboard is at http://localhost:9170 (localhost-only). Logs:

docker logs -f keikaku-agent

Run multiple agents

They all share the one Ollama (one model in VRAM). Use the Compose bundle from the app and scale it:

docker compose up -d --scale agent=3

Mind your VRAM — more agents means more concurrent requests queued against the same model.

Update / stop

docker pull ghcr.io/keikaku-ai/agent:latest && docker restart keikaku-agent
docker stop keikaku-agent      # stop
docker rm -f keikaku-agent     # remove