// get started · 02
Installation
The only prerequisite is git. The installer uses uv as its engine — it downloads Python 3.11+, creates the isolated environment and installs everything. You don't n…
Linux / macOS / WSL
curl -fsSL https://okamiagent.com/install.sh | bashgit clone https://github.com/OkamiOps/Okami-Agent
cd Okami-Agent
./scripts/install.shWhat the installer does
- Detects (or downloads via uv) Python 3.11+ and creates an isolated venv.
- Installs the package and exposes the global
okamicommand. - Doesn't touch your system Python and needs no sudo.
Windows (PowerShell)
irm https://okamiagent.com/install.ps1 | iexDocker (any OS)
docker build -f deploy/Dockerfile -t okami-agent .
docker compose -f deploy/docker-compose.yml run --rm okami doctor
docker compose run --rm okami run "say hi"For an LMStudio running on the host machine, point api_base to http://host.docker.internal:PORT/v1.
Run from source (dev)
uv sync # creates the venv + deps from pyproject
uv run okami doctor # runs without activating anything
uv tool install -e . # editable global (optional)Optional extras
| extra | enables |
|---|---|
| uv sync --extra voice | voice: faster-whisper (STT) + edge-tts (TTS) |
| uv sync --extra honcho | honcho-ai memory backend |
| uv sync --extra browser | browser automation via Playwright |
| uv sync --extra dev | pytest (test suite) |
Verify the install
okami doctor is your first command: it checks providers, keys, connectivity, the toolchain (git, uv, node, docker, claude), SQLite FTS5 support, the memory embedder and the sandbox policy. Use --json for CI and --lint for a security-posture lint.
Troubleshooting
| symptom | cause · fix |
|---|---|
| okami not found | stale PATH → reopen the terminal |
| claude_cli not ready | install and log in to the claude CLI |
| codex not authed | run okami login codex |
| SQLite FTS5 missing | memory falls back to LIKE → use a Python with FTS5 |
| embedder offline | degrades to BM25 automatically (fine) |
| Windows long-path | use a short venv path, e.g. C:\okv |