Skip to main content

​
voss is not found

Install the CLI package:
Then verify:
If you manage Python yourself, pip install "voss @ git+https://github.com/voss-lang/voss" installs the Python package directly from GitHub. For Voss development, use pip install -e ".[dev]" from a source checkout.

​
Bare voss opens the plain chat instead of the Go client

The Go client binary was not found, so Voss fell back to the plain chat. The npm package includes it. From a source checkout, build it with (cd tui && go build -o voss-tui .), or point VOSS_TUI_BIN at a binary. Check that VOSS_USE_TUI is not set to 0.

​
Provider or model setup fails

Run diagnostics:
Then inspect config:
If no credentials are found, run voss login. In CI or other non-interactive shells the wizard is skipped, so set ANTHROPIC_API_KEY or OPENAI_API_KEY instead.

​
MCP tools or web tools are missing

Network tools, including MCP, are off by default. Start with voss chat --allow-net, or set [tools] allow_net = true in config.toml (the Go client reads this setting). Use voss mcp list --configured to see which servers Voss discovered without connecting to them. Discovery does not carry over remote MCP OAuth sessions, and legacy SSE endpoints need a Streamable HTTP endpoint.

​
The agent will not edit a file

Check the current mode and scope.
  • plan mode denies mutating tools.
  • edit mode only allows scoped file writes.
  • shell_run is denied in edit mode.
Use voss edit <path> for bounded edits, or explicitly approve scope expansion when Voss asks.

​
A .voss file does not run

Check it first:
Then run:

​
Docs commands fail

Install the Mintlify CLI globally:
Run docs commands from the site package: