venom CLI quickstart
Install the venom CLI, point it at a model, run a first session and check the setup with venom doctor.
From nothing to a first session in a few minutes. The CLI page has the downloads.
Install
On macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | shThe script picks the build for your OS and chip, downloads it and SHA256SUMS from the public releases repository, checks the hash, unpacks it and links ~/.venom/bin/venom. If ~/.venom/bin is not on your PATH it prints the line to add. Each build includes its own Node runtime, so nothing else is needed.
To install by hand, download the archive for your platform, check it with shasum -a 256 -c SHA256SUMS --ignore-missing, unpack it anywhere and run bin/venom. Install venom covers the installer's options, Windows, updates, uninstalling and building from source.
venom --versionPick a model
venom speaks the OpenAI API. VENOM_BASE_URL says where to send requests, VENOM_API_KEY is the key for that endpoint (if it needs one) and VENOM_MODEL picks the model. Put the exports in your shell profile to keep them.
Offline, with Ollama on your machine:
ollama pull qwen3:8b
export VENOM_BASE_URL=http://localhost:11434/v1
export VENOM_MODEL=qwen3:8bWith Venom Cloud, using a vck_ key from the console (cloud quickstart has the steps):
export VENOM_BASE_URL=https://cloud.usevenom.dev/v1
export VENOM_API_KEY=vck_…Any other OpenAI-compatible endpoint (vLLM, SGLang, llama.cpp, a gateway or a provider) works the same way: its base URL including /v1, its key and a model it serves.
| Variable | What it sets | Default |
|---|---|---|
VENOM_BASE_URL |
The OpenAI-compatible endpoint, including /v1 |
http://localhost:8787/v1 (a local orchestrator) |
VENOM_API_KEY |
The key for that endpoint | none (no Authorization header) |
VENOM_MODEL |
The model to use | venom-default (the orchestrator's default alias) |
Local or cloud models compares the options (Ollama, the desktop daemon, your own orchestrator, Venom Cloud, a provider) and shows how to save the endpoint in ~/.venom/config.yaml instead of exporting it.
A first session
Start venom in your project:
cd ~/work/app
venom # the interactive agent
venom -p "explain this repo" # one prompt, printed answer
venom -c # continue the last session herevenom init proposes an AGENTS.md and starter permission rules for the project. If the project is set up for Claude Code, venom reads its CLAUDE.md, skills, commands, agents, settings and .mcp.json as they are. Hooks, MCP servers and allow rules from a project take effect only once you trust it; venom asks the first time.
What the first run looks like
Trust. In a project that ships configuration that can run code or loosen permissions (hooks, MCP servers, allow rules, plugins), venom lists what would run and asks: Trust this project, Trust parent folder, Don't trust (ignore it), or Decide later. Until you trust it, venom ignores those items and runs with your own settings only.
venom trustasks the same question from a shell (venom trust --yeswithout a terminal),venom trust --listshows your decisions andvenom trust --revokeundoes one.--approvetrusts a project for one run.The prompt. Type a request and press Enter. The agent reads files, runs commands and edits; anything your mode and rules don't allow asks you first. Esc stops the current turn.
The status bar at the bottom shows the directory and git branch, then the permission mode and sandbox, the context window used, running subagents, the session's cost and tokens, and the model with its thinking level:
~/work/app ⎇ main ⏵ edits sbx ctx 42% 2 agents 1 wait $0.012 12k↑ 3.1k↓ 50k⚡ gpt-5.4-mini high
Useful from the start: ctrl+g ? lists every key binding, typing / lists the slash commands, /model switches models, /undo takes back the last file change, and /context and /cost show what the session holds and has spent. To switch between cheap and strong models in one keystroke, see Your first gear.
Permission modes
Switch with alt+m or /mode. Rules apply as deny, then ask, then allow. Shell commands are parsed, and each part of a compound command is judged on its own. A short list of destructive commands (such as rm -rf ~ or piping curl into a shell) is denied in every mode.
| Mode | What it allows |
|---|---|
plan |
Read-only. The agent explores and proposes a plan; no file changes, no commands that write. |
default |
Edits and commands your rules don't allow ask you first. |
accept-edits |
Edits in the workspace go ahead; commands still ask. |
yolo |
Runs without asking. Bash runs inside the OS sandbox on macOS and Linux: writes stay in the workspace and temp dirs, network through an allowlist. |
Your own rules live in ~/.venom/permissions.json; settings in ~/.venom/config.yaml, or a venom.yaml in the project.
Check the setup
venom doctorIt checks the endpoint (reachable, your key, the models and their context windows), the OS sandbox, what the current project loads and where your prompts go, and prints PASS, WARN or FAIL with a fix on each line. venom doctor --probe also sends the model a short chat and a tool call. Troubleshooting lists every flag and the common failures.
Update
Run the install line again; it installs the newest release next to the old one and moves the link. Set VENOM_VERSION to install a specific version.
Windows (beta)
In PowerShell:
irm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.ps1 | iexIt installs to %USERPROFILE%\.venom\bin and adds that to your user PATH. Windows has no OS sandbox, and venom says so when it starts: in yolo, commands your rules don't allow still ask, and auto mode is unavailable. For the full sandbox, run the Linux build in WSL.
Next steps
- Venom Cloud quickstart: one endpoint for your GPUs, trusted public nodes and provider keys.
- Your first gear: presets of models you switch with
ctrl+gand a number. - Troubleshooting:
venom doctorand the common problems. - API reference: the HTTP APIs of
venom serve, the orchestrator and Venom Cloud.