Skip to content
Docs menu

Configuration

Where venom reads its settings from, which file or variable wins, and how to see, check and change the configuration in force.

View .md

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

venom config init        # writes a commented starter ~/.venom/config.yaml
# ~/.venom/config.yaml
model: venom-default
thinking:
  venom-default: medium
gear: normal
ui:
  theme: auto
  width: auto
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

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

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

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.

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
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

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

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)
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

In this section

  • venom.yaml reference: Every key venom.yaml accepts, with its type, default, the environment variable that overrides it and whether a project file needs trust.
  • Gears: 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: 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: 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: The VENOM_* environment variables the CLI reads, what each sets, its default, and the venom.yaml key it overrides.