---
title: venom CLI quickstart
description: Install the venom CLI, point it at a model, run a first session and check the setup with venom doctor.
section: getting-started
order: 10
audience: [user]
sources: [scripts/release/public/install.sh, docs/getting-started.md, docs/configuration.md, packages/harness/src/provider/index.ts]
features: []
---

From nothing to a first session in a few minutes. The [CLI page](/cli) has the downloads.

## Install {#install}

On macOS or Linux:

```bash
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | sh
```

The script picks the build for your OS and chip, downloads it and `SHA256SUMS` from the [public releases repository](https://github.com/elishahbiz/venom-releases/releases/latest), 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](/docs/getting-started/install.md) covers the installer's options, Windows, updates, uninstalling and building from source.

```bash
venom --version
```

## Pick a model {#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:

```bash
ollama pull qwen3:8b
export VENOM_BASE_URL=http://localhost:11434/v1
export VENOM_MODEL=qwen3:8b
```

With Venom Cloud, using a `vck_` key from the console ([cloud quickstart](/docs/getting-started/cloud-quickstart.md) has the steps):

```bash
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](/docs/getting-started/local-or-cloud.md) 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 {#session}

Start venom in your project:

```bash
cd ~/work/app
venom                          # the interactive agent
venom -p "explain this repo"   # one prompt, printed answer
venom -c                       # continue the last session here
```

`venom 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 {#first-run}

1. **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 trust` asks the same question from a shell (`venom trust --yes` without a terminal), `venom trust --list` shows your decisions and `venom trust --revoke` undoes one. `--approve` trusts a project for one run.
2. **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.
3. **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:

   ```text
   ~/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](/docs/getting-started/first-gear.md).

## Permission modes {#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 {#doctor}

```bash
venom doctor
```

It 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](/docs/getting-started/troubleshooting.md) lists every flag and the common failures.

## Update {#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) {#windows}

In PowerShell:

```powershell
irm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.ps1 | iex
```

It 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](/docs/getting-started/cloud-quickstart.md): one endpoint for your GPUs, trusted public nodes and provider keys.
- [Your first gear](/docs/getting-started/first-gear.md): presets of models you switch with `ctrl+g` and a number.
- [Troubleshooting](/docs/getting-started/troubleshooting.md): `venom doctor` and the common problems.
- [API reference](/docs/api): the HTTP APIs of `venom serve`, the orchestrator and Venom Cloud.
