Skip to main content
The recommended install path is the npm CLI package. It vendors Python 3.12, the Voss wheel, and the Go terminal client (voss-tui), so you do not need to manage a Python environment just to run the harness.

​
Prerequisites

  • Node.js 18 or newer for the npm package
  • Python 3.11 or newer if you install with pip or from source
  • Git
  • A terminal environment where Voss can run inside a repository
npm platform packages are published for macOS (Apple silicon), Linux (x64 and arm64), and Windows (x64).

​
Alternative: pip

If you already manage Python 3.11+ yourself, install from GitHub. Voss is not published to PyPI, and the voss package there is an unrelated project.
Semantic memory/search dependencies are optional because they pull heavier vector-search packages:

​
Container image

A CLI image is published to GitHub Container Registry. Mount a repo into /workspace for project-scoped commands:

​
Source checkout

Use an editable checkout for Voss development:
To use the Go terminal client from a checkout, build it once. Editable installs pick up the local build automatically:

​
Verify the CLI

voss doctor checks local harness prerequisites such as config directories, provider setup, compiler availability, and tool readiness.

​
Sign in

The sign-in wizard offers Claude Code OAuth, Codex / ChatGPT OAuth, or a pasted Anthropic or OpenAI key stored in the OS keychain. Remove a stored key with voss logout anthropic or voss logout openai. In CI, set ANTHROPIC_API_KEY or OPENAI_API_KEY instead; the wizard is skipped when stdin is not a terminal.
Use npm i -g @vosslang/cli for normal CLI use. Use pip install -e ".[dev]" when you are changing Voss itself.

​
Next steps