---
title: Configuration
description: Where venom reads its settings from, which file or variable wins, and how to see, check and change the configuration in force.
section: configuration
order: 0
audience: [user, operator, builder, agent]
sources: [packages/harness/src/config/index.ts, packages/harness/src/config/schema.ts, cli/src/venom-config.ts, cli/src/nl-config.ts, docs/configuration.md, docs/venom-config.schema.json]
features: [configuration.config]
---

venom reads one YAML file format, `venom.yaml`, from up to three places, so a team can commit a project file while each person keeps their own defaults in their home directory. Flags and `VENOM_*` environment variables override every file. Every key is optional: with no file at all, venom runs on built-in defaults against a local orchestrator.

## A minimal file {#example}

```bash
venom config init        # writes a commented starter ~/.venom/config.yaml
```

```yaml
# ~/.venom/config.yaml
model: venom-default
thinking:
  venom-default: medium
gear: normal
ui:
  theme: auto
  width: auto
```

```bash
venom config             # every value in force, and the file or variable it came from
venom config validate    # unknown keys, wrong types, secrets, gear problems; exit 1 on any
```

## Where the files are {#files}

| Level | File | Typical owner |
|---|---|---|
| Current directory | `./venom.yaml`, else `./.venom/config.yaml` | a sub-project or monorepo package |
| Repository root | `<git toplevel>/venom.yaml`, else `.venom/config.yaml`, when it is not the current directory | the team, committed |
| Home | `~/.venom/config.yaml` (`$VENOM_HOME/config.yaml`) | you |

`venom.yaml` is the canonical name. When both `venom.yaml` and `.venom/config.yaml` exist in one directory, `venom.yaml` wins and `venom config validate` warns about the other. A directory that resolves to your home config is read once, as home.

## Precedence {#precedence}

Highest first:

1. command-line flags (`--model`, `--plan`, `--offline`, …)
2. environment variables (`VENOM_MODEL`, `VENOM_BASE_URL`, …)
3. the current directory's file
4. the repository root's file
5. the home file
6. built-in defaults

Files merge key by key: maps merge deeply, a list replaces the list below it, and `null` unsets a key so the value below it (or the default) applies. The config only fills environment variables you left unset, so `VENOM_MODEL=x venom` and `venom --model x` still win over `model:` in any file. `thinking:` is the exception that merges: the file's entries and `VENOM_THINKING` are combined, and the variable wins per model.

An organisation policy (`/etc/venom/policy.json`, or the one Venom Cloud signs) wins over all of it: an `orchestrator.base_url` other than the policy's pin is ignored with a warning.

Which keys reach which commands:

| Keys | Apply to |
|---|---|
| `model`, `tiers`, `thinking`, `vision_model`, `decision_model`, `search`, `orchestrator` | every command (TUI, `-p`, `venom serve`, `venom acp`, `venom review`, …), through the environment |
| `permissions`, `agents`, `browser`, `ui`, `statusline`, `context`, `gear`, `gears`, `keys`, `workspaces`, `hooks` | the TUI and print mode (`venom -p`) |
| `sounds`, `voice` | the TUI |
| `plugins` | every command that starts a session |

## Project files and trust {#trust}

A repository's `venom.yaml` was written by whoever wrote the repository. Until you trust the project (`venom trust`, or the trust dialog the TUI shows the first time), a project file can only tighten. These keys are ignored, with a warning, from an untrusted project file:

| Key | Why it needs trust |
|---|---|
| `permissions.mode` past `default` (`accept-edits`, `auto`, `yolo`), `permissions.allow` | loosens permissions |
| `orchestrator.base_url` | decides where your prompts go |
| `search.url`, `search.brave_key_env`, `search.tavily_key_env` | decides where queries go and which keys they use |
| `workspaces.dir`, `workspaces.copy_ignored`, `workspaces.create`, `workspaces.finish` | writes files and runs commands |
| `inbox.attention`, `serve.public_url`, `memory.dir`, `memory.org_dir`, `schedules`, `guardrails.rules` | changes what reaches you, where files go, or runs prompts unattended |
| `tasks.lookup`, `tasks.pr_footer`, `review.model`, `review.before_pr`, `review.max_usd` | calls GitHub or spends money |
| `plugins.sources` | plugins run code |
| `hooks` entries with a `command` | runs commands (sound-only hooks need no trust) |

`mcp.enabled` is read from the home file only; a project file may add to `mcp.disabled` but never remove from it. `sudo` is never a saved mode at any level. Model choices, gears, keys and UI preferences apply from any level.

Trust covers the file's content: when a trusted project's `venom.yaml` gains a loosening key, venom asks again. `--approve` (`-a`) trusts the project for one run and `--no-approve` ignores its loosening keys for one run.

> [!WARNING]
> Never put a key or token in a config file. The loader drops any key named like a credential (`api_key`, `token`, `password`, `secret`, `auth`, …) and any value shaped like one (`sk-…`, `ghp_…`, `glpat-…`, a JWT, a private key, `user:password@` in a URL), with a warning that names the key, never the value. Keys come from the environment; to use a search key under another variable name, name the variable (`search: { brave_key_env: MY_BRAVE_KEY }`).

## venom config {#venom-config}

| Command | What it does |
|---|---|
| `venom config` (also `venom config show`) | the config files found, then every value in force with its source (`env VENOM_MODEL`, or the file), then the gears |
| `venom config --json` | the same as JSON: `{ files, trusted, config, entries, warnings }` |
| `venom config --paths` | the config files found, closest first |
| `venom config validate [--offline]` | unknown keys (with a "did you mean"), wrong types, secrets, each plugin's `config` against its manifest, and gears (cycles, bad names and keys, and, unless `--offline`, models and route profiles against the orchestrator's `/v1/models` or the model cache). Exit 1 on any problem |
| `venom config init [--home \| --repo \| --cwd] [--force]` | writes a commented starter file: `--home` (the default) `~/.venom/config.yaml`, `--repo` `<repo root>/venom.yaml`, `--cwd` `./venom.yaml`. Refuses to overwrite without `--force` |
| `venom config schema` | prints the JSON Schema |
| `venom config set <key> <value>` | sets one dotted key in `~/.venom/config.yaml`, checked against the schema first, comments kept (`venom config set workspaces.default session`). `true`, `false`, `null`, numbers and JSON lists or objects are parsed; anything else is a string |
| `venom config unset <key>` | removes the key from the home file |
| `venom config "<sentence>" [--project] [--yes] [--dry-run] [--model <id>]` | describe a change in words; see [Change it by asking](#by-asking) |
| `venom config packages` | pi's own `config` command (package resources), which `venom config` replaces |

In the TUI, `/config` prints the same table as `venom config`, and `/config <sentence>` drafts a change.

`venom config init` also writes the schema to `~/.venom/venom-config.schema.json` and puts a `# yaml-language-server: $schema=…` line at the top of the starter, so editors with the YAML language server complete and check keys offline.

### Change it by asking {#by-asking}

`venom config "warn me above $3 a session"` (or `/config warn me above $3 a session`) sends one small request to the engaged gear's `classifier` role, else its fast model, else `tiers.fast` (`--model` overrides). The reply must be a patch that passes the schema. venom shows the YAML diff with a one-line explanation and writes only when you confirm.

| Flag | Effect |
|---|---|
| `--yes`, `-y` | confirm in advance |
| `--dry-run` | show the diff, never write |
| `--project` | write `./venom.yaml` instead of the home file (needs a trusted project) |
| `--model <id>` | the model that drafts the patch |

Without a terminal and without `--yes`, nothing is written. A permission mode or allow rule the organisation policy forbids is refused with the policy's reason. Keys that run commands (`hooks`, `plugins.sources`, `workspaces.create`, `workspaces.finish`) are never drafted, and permission rule lists are added to, not replaced.

## Other files venom reads {#other-files}

| File | What |
|---|---|
| `~/.venom/permissions.json` | your permission rules, alongside `permissions:` in venom.yaml |
| `.claude/settings.json`, `CLAUDE.md`, `.mcp.json` | Claude Code project files, read as they are |
| `~/.venom/themes/`, `.venom/themes/` | theme files ([Themes](/docs/configuration/ui-and-themes.md#themes)) |
| `config/orchestrator.yaml` | the orchestrator's own config (upstreams, routes, route profiles). Its path is `VENOM_CONFIG` for the orchestrator process; the CLI never reads that variable |

## Troubleshooting

| Symptom | Cause and fix |
|---|---|
| A value in your file has no effect | A flag or a `VENOM_*` variable sets it, or a closer file does. `venom config` names the winning source |
| `ignored: … needs the project to be trusted` | A loosening key in an untrusted project file. Run `venom trust`, or move the key to `~/.venom/config.yaml` |
| `… looks like a secret; dropped` | A credential-shaped key or value. Put the key in the environment and name the variable |
| `unknown key … (did you mean …)` | A typo or an old key; the key is dropped and the rest of the file still loads. Nothing in a file stops venom from starting |
| `/width` says another file wins | A project file sets the same `ui` key; the project file wins over the home file |

## Related

- [venom.yaml reference](/docs/configuration/venom-yaml.md): every key, type and default.
- [Environment variables](/docs/configuration/env-vars.md): every variable and the key it matches.
- [Gears](/docs/configuration/gears.md), [Models](/docs/configuration/models.md), [UI, themes and keys](/docs/configuration/ui-and-themes.md).
- [venom CLI quickstart](/docs/getting-started/cli-quickstart.md).


## In this section {#in-this-section}

- [venom.yaml reference](/docs/configuration/venom-yaml.md): Every key venom.yaml accepts, with its type, default, the environment variable that overrides it and whether a project file needs trust.
- [Gears](/docs/configuration/gears.md): Switch the main model, thinking level, delegation models and route profile in one keystroke, use the built-in gears, and define your own.
- [UI, themes and keys](/docs/configuration/ui-and-themes.md): Set the TUI's reading width, transcript, HUD, statusline, colour theme, leader key and gear hotkeys in venom.yaml.
- [Models, offline mode and tool billing](/docs/configuration/models.md): Choose the main, delegation, vision and decision models and their thinking levels, point venom at an orchestrator, and configure offline mode, tool billing, tests after edits and learned skills.
- [Environment variables](/docs/configuration/env-vars.md): The VENOM_* environment variables the CLI reads, what each sets, its default, and the venom.yaml key it overrides.
