Every key venom.yaml accepts, with its type, default, the environment variable that overrides it and whether a project file needs trust.
The JSON Schema (venom config schema, also docs/venom-config.schema.json in the source tree) is the source of truth for this page. Every key is optional. An unknown key or a wrong type is dropped with a warning and the rest of the file loads. "Trust" marks keys a project file may set only once the project is trusted (Project files and trust).
Start a file with the schema line so your editor checks it:
$schema: ~/.venom/venom-config.schema.json
Models
| Key |
Type |
Default |
Env var |
Meaning |
model |
string |
venom-default |
VENOM_MODEL |
the main model (id or alias) |
thinking |
map model → off | minimal | low | medium | high | xhigh |
venom-fast: off, venom-default: medium |
VENOM_THINKING (wins per model) |
default reasoning effort per model id or alias |
tiers.fast |
string |
venom-fast when served |
VENOM_FAST_MODEL |
the fast tier: the explorer, compaction summaries, agents with model: fast |
tiers.smart |
string |
venom-smart when served |
VENOM_SMART_MODEL |
the smart tier: agents with model: smart |
agents.<name>.model |
string |
the agent file's |
|
a model (id, alias or tier) for one agent: agents: { explorer: { model: qwen-fast } }. A task call's own model still wins |
vision_model |
string |
venom-vision |
VENOM_VISION_MODEL |
describes images for a text-only main model |
decision_model |
string |
venom-decide |
VENOM_DECISION_MODEL |
the decision model auto mode's decider and search re-ranking ask |
orchestrator.base_url |
URL with /v1 |
http://localhost:8787/v1 |
VENOM_BASE_URL |
where models are served. Trust. The key stays in VENOM_API_KEY |
gear |
key (1–12) or name |
none |
|
the gear engaged at startup |
gears |
map name or key → gear |
the nine built-ins |
|
your gears and patches to the built-ins; see Gears |
Details: Models.
Search and browser
| Key |
Type |
Default |
Env var |
Meaning |
search.url |
URL |
none |
VENOM_SEARCH_URL |
your SearxNG, tried first by web_search. Trust |
search.brave_key_env |
variable name |
BRAVE_API_KEY |
|
the variable holding the Brave Search key (never the key). Trust |
search.tavily_key_env |
variable name |
TAVILY_API_KEY |
|
the variable holding the Tavily key. Trust |
search.orchestrator |
on | off |
on |
VENOM_SEARCH_ORCHESTRATOR |
on: ask the orchestrator's /v1/search first; off: only the direct backends, then DuckDuckGo |
search.rerank |
on | off |
off |
VENOM_SEARCH_RERANK |
re-rank results with the decision model |
browser |
on | off | window | headless | extension |
on |
|
on: browser tools load lazily when a Chrome is installed; off = --no-chrome, window = --chrome, headless = --chrome-headless, extension = --chrome-extension. A flag wins |
UI
Full descriptions in UI, themes and keys.
| Key |
Type |
Default |
Meaning |
ui.width |
40+ | auto | full |
auto (100 columns) |
reading width; VENOM_MAX_WIDTH wins; /width saves here |
ui.verbosity |
quiet | normal | full |
quiet |
how much of each turn the transcript shows; /verbose saves here |
ui.meter |
on | off | compact | full |
compact |
the call meter under each turn (on = compact); /meter saves here |
ui.agents_panel |
on | off | auto |
auto |
the agents panel; /agents-panel saves here |
ui.theme |
theme name | auto |
auto |
colour theme; /theme saves here |
ui.theme_overrides |
map token → #rrggbb |
none |
single colours over the active theme |
ui.hud |
auto | compact | full | custom |
auto |
the status bar layout; /hud saves here |
ui.hud_lines |
list of lists of segment ids |
the full layout |
the custom HUD's lines |
ui.hud_thresholds.warn, ui.hud_thresholds.crit |
percent |
50, 80 |
amber and red levels for the HUD's percentages |
ui.clock |
full | time | date | off |
full |
the HUD's lower-right corner |
ui.clock_format |
12h | 24h |
the locale's |
clock hours |
ui.location |
string |
the time zone's city |
the place shown in the HUD, derived offline |
ui.pr_pane.side |
right | left |
right |
where the pull requests pane opens |
ui.pr_pane.width |
columns | "45%" |
half the terminal, 44–120 |
the pane's width |
ui.pr_pane.auto_refresh |
true | false | seconds |
true (60 s) |
refresh while the pane is open |
statusline |
list of widgets |
none |
one extra status line; UI only, never sent to the model |
keys.leader |
key |
ctrl+g |
the leader (prefix) key |
keys.leader_timeout_ms |
integer |
1500 |
how long the leader waits for its key |
keys.leader_bindings |
map key → action |
the defaults |
what the key after the leader does; null removes one |
keys.gear_hotkeys |
boolean |
true |
shift+F1…F12, alt+1…9, alt+. and alt+, for gears |
Context and memory
| Key |
Type |
Default |
Meaning |
context.autocompact |
share 0.2–0.95 | off |
the model's hard threshold (0.55 for an unknown model) |
where automatic compaction starts, as a share of the window. off: only when the next request would not fit. /compact works either way |
context.quality.<model or prefix*>.soft |
share |
per model family |
past it, idle compaction runs |
context.quality.<model or prefix*>.hard |
share |
per model family |
past it, the compaction trigger fires (unless context.autocompact is set) |
context.idle_compact |
seconds | off | { after, headless } |
180, interactive only |
compact in the background after this long idle when past the soft threshold. context.idle_compact.after is the seconds; context.idle_compact.headless: true also in venom serve, ACP and print mode |
memory.auto |
on | off |
on |
load the project's MEMORY.md index into each session and give the model the memory tool and /memory |
memory.dir |
path |
~/.venom/projects/<slug>/memory |
where memory files go (absolute, ~/…, or relative to the project root). Trust |
memory.max_index_lines |
integer |
200 |
index lines loaded into the prompt (at most 12 KiB) |
memory.org_dir |
path |
none |
a shared directory of org-wide memory every machine reads. Trust |
VENOM_CONTEXT_WINDOW caps the context window venom assumes: the smaller of the server-reported window and this value, or this value when the server reports none (default 131072).
Workspaces
| Key |
Type |
Default |
Meaning |
workspaces.default |
off | session | subagents | both |
off |
when venom uses git worktrees without being asked: every interactive session, every writing subagent, or both |
workspaces.dir |
path |
.venom/worktrees |
where worktrees go, relative to the repository root. Trust |
workspaces.branch_prefix |
string |
venom/ |
each workspace's branch is <prefix><name> |
workspaces.cleanup |
auto | keep | ask |
auto |
when a session in a workspace ends: remove it if nothing would be lost, always keep it, or ask |
workspaces.copy_ignored |
list of patterns |
[.env.example] |
gitignored files copied into a new workspace; a secret-named file only when a pattern names its exact path. Trust |
workspaces.create |
command or list |
none |
run with sh -c in each new workspace; KEY=VALUE lines it prints go into the agent's environment there. Trust |
workspaces.finish |
command or list |
none |
run just before venom removes a workspace. Trust |
workspaces.timeout_ms |
integer |
120000 |
kill create and finish after this long |
Permissions and guards
| Key |
Type |
Default |
Meaning |
permissions.mode |
plan | default | accept-edits | auto | yolo |
default |
the starting permission mode. A project file needs trust past default; --permission-mode, --yolo, --plan win |
permissions.allow |
list of rules |
none |
allow rules (bash(npm test:*), edit(src/**)), on top of ~/.venom/permissions.json. Trust |
permissions.ask |
list of rules |
none |
ask rules |
permissions.deny |
list of rules |
none |
deny rules |
permissions.auto.timeout_ms |
integer |
none (the classifier request's own 30 s) |
give up on one auto-mode review after this long; VENOM_AUTO_TIMEOUT_MS wins |
permissions.auto.on_failure |
ask | deny |
ask |
a failed or timed-out review hands the call to you (headless: denied) or denies it; VENOM_AUTO_ON_FAILURE wins |
guards.output_budget |
integer tokens |
none |
output tokens a run is meant to use (also --output-budget); a model that stops early is nudged to keep going, at most 3 times |
stuck.oscillations |
integer |
2 |
times one file may go back to an earlier version before the session counts as stuck (0: off) |
stuck.repeated_failures |
integer |
3 |
times the same call may fail the same way (0: off) |
stuck.escalate |
boolean |
true |
shift up one gear before asking you |
stuck.gear |
gear name |
next of eco → normal → power |
the gear to shift to |
session_guard.stall_calls |
integer |
12 |
model calls in a row with no progress before the session pauses (0: off) |
session_guard.max_minutes |
integer |
no limit |
pause after this many minutes since your last message |
session_guard.max_usd |
number |
no limit |
pause after this much spend since your last message, at list price |
guardrails.catalog |
list of ids |
none |
built-in guardrails to switch on (/guardrails catalog lists them) |
guardrails.rules |
list of rules |
none |
your own guardrails (fields code, name, kind, action, mode, enabled, match, direction, paths, repos, models, tools, limit, answer, description). Trust |
guardrails.rules[].kind is one of content, routing, models, tools, spend, answers; action one of block, deny, keep_local, downgrade, ask, redact, rewrite, warn, log; mode enforce or monitor; direction request, response or both. The guardrail format itself is documented in Guardrails.
Long tasks, reviews and cost
| Key |
Type |
Default |
Meaning |
resume.checkpoints |
boolean |
true |
write a checkpoint to ~/.venom/tasks/ at each turn and plan step; false also turns off venom resume and the limit wait |
resume.on_limit |
wait | fail |
wait |
a 429 naming a reset time parks the task until then, or ends the run |
resume.fallback_gear |
gear name |
none |
switch to this gear at once on a usage limit instead of waiting |
resume.max_wait_hours |
number |
12 |
the longest a task waits on one limit |
resume.prompt |
boolean |
true |
on a terminal, ask at start whether to resume an interrupted task here |
plan_execute.approve |
ask | auto |
ask |
show a plan-then-execute plan and wait for Run / Edit / Cancel, or run it as written (headless always runs it) |
review.before_pr |
boolean |
true |
review the branch's diff before the agent runs gh pr create; --no-self-review skips one run. Trust |
review.model |
model |
the gear's smart tier |
the self-review's model, also venom review's default. Trust |
review.gear |
gear name |
none |
the gear venom review runs on without --model or --gear |
review.rounds |
integer |
1 |
times a pull request may be held back for fixes (0: no review) |
review.max_usd |
number |
2 |
stop one self-review at this cost. Trust |
tasks.lookup |
git | gh |
git |
how a session's task is found: the branch offline, or also gh pr view. Trust |
tasks.pr_footer |
off | body | comment |
off |
write the task's spend into the pull request venom opened. Trust |
tool_billing.<tool> |
billing entry |
none (tools are free) |
what a non-built-in tool costs; see Tool billing |
tests.on_edit, tests.max_seconds, tests.flaky_after |
see Tests |
auto, 60, 3 |
tests after edits and the flaky-test detector |
learn |
boolean |
true |
draft a template or skill after the same kind of job three times (Learned skills) |
finetune.enabled |
boolean |
false |
let venom finetune export and venom export-traces read your saved sessions |
finetune.since |
date |
none |
sessions last modified before it are never read |
finetune.trainer |
unsloth | axolotl | llama-finetune |
auto (first on PATH) |
the local trainer venom finetune train runs |
finetune.base_model |
path |
none |
the local base model the trainer starts from |
offline.auto, offline.gear |
boolean, gear name |
true, local |
switch to a local gear when the network drops (Offline mode) |
venom serve, inbox and schedules
| Key |
Type |
Default |
Meaning |
serve.public_url |
URL |
none |
the address phones and teammates reach this machine's venom serve at; VENOM_SERVE_PUBLIC_URL overrides. Trust |
inbox.attention.minutes_per_day |
number |
no cap |
minutes of your attention agents may use per local day; low-value items over it are held. Trust |
inbox.attention.threshold |
number |
0 |
lowest rank that reaches you. Trust |
schedules.<job> |
job |
none |
a background agent venom serve runs on a cron or on events. Trust |
A job takes schedules.<job>.cron (five fields, local time, or @hourly, @daily, @weekly, @monthly, @yearly), on (events that also start it), role (dependency-bumper, flaky-hunter, dead-code, docs-drift, or a plugin's), prompt, cwd (inside a venom serve --root), workspace (default true), gear, model, mode (default default, every question answered no), max_usd (default 1), max_minutes (default 120, 0: no limit), enabled, allow (rules the run may use without asking), and for recorded browser scripts browser_task, params, browser (headless, launch, extension, attach) and attach_port. venom schedule add|list|rm|run manages them; the automation section documents schedules in full.
MCP, library and plugins
| Key |
Type |
Default |
Meaning |
mcp.enabled |
list of names |
none |
approved MCP servers you turned on (home file only; venom mcp enable writes it) |
mcp.disabled |
list of names |
none |
approved servers you turned off; lists from every file add up |
library.hidden |
list of names |
none |
team library items you don't want: a name, org:<name>, skill:<name>. Required items still load |
plugins.sources |
list of path: / npm: / git: sources |
none |
plugins to load; venom plugin add writes it. Trust |
plugins.<name>.enabled |
boolean |
true |
false lists the plugin without loading it |
plugins.<name>.config |
map |
the plugin's defaults |
the plugin's settings, checked against its manifest by venom config validate |
Hooks, sounds and voice
| Key |
Type |
Default |
Meaning |
hooks |
list |
none |
commands or sounds on venom events. Every file's list runs, home first; a project file's commands only while the project is trusted |
hooks[].event |
MainAgentDone | SubagentDone | StepDone | PermissionNeeded | AgentFailed | ScheduleDone |
required |
the event |
hooks[].matcher |
regex |
all |
anchored, over the agent name or role, or the tool name for StepDone and PermissionNeeded |
hooks[].command |
shell command |
none |
gets the event's JSON payload on stdin |
hooks[].sound |
name or absolute path |
none |
a sound played instead of, or as well as, the command |
hooks[].timeout |
seconds |
30 |
kill the command after this long |
hooks[].async |
boolean |
true |
don't wait for the command; events never block the agent either way |
sounds.enabled |
boolean |
true |
play event sounds at all |
sounds.volume |
0–1 |
0.6 |
volume |
sounds.only_when_unfocused |
boolean |
true |
only while the terminal is in the background (a terminal that reports no focus plays) |
sounds.quiet_hours |
"HH:MM-HH:MM" |
none |
no sounds in this local window (wraps midnight) |
sounds.min_turn_seconds |
seconds |
5 |
no done sound for shorter runs |
sounds.events.main_agent_done |
sound | path | off |
chime |
|
sounds.events.subagent_done |
sound | path | off |
tick |
|
sounds.events.step_done |
sound | path | off |
off |
|
sounds.events.permission_needed |
sound | path | off |
attention |
|
sounds.events.agent_failed |
sound | path | off |
failure |
|
sounds.events.schedule_done |
sound | path | off |
done |
|
voice.model |
path |
~/.venom/models/ggml-base.en.bin |
the whisper.cpp model for voice input (ctrl+g r, /voice) |
voice.language |
code |
en |
whisper's language; auto detects it |
Built-in sounds: chime, done, tick, pop, bell, hiss, success, failure, attention, marimba. VENOM_SOUND_PLAYER sets your own player command. Claude Code-style hooks stay in .claude/settings.json; the automation and plugins sections cover hook payloads and Claude Code hooks.
A full example
model: venom-default
tiers: { fast: venom-fast, smart: venom-smart }
thinking: { venom-default: medium, venom-fast: off }
gear: normal
gears:
review:
key: 10
extends: power
mode: plan
permissions:
mode: default
deny: ["bash(git push:*)"]
tests: { on_edit: auto, max_seconds: 90 }
workspaces: { default: subagents }
context:
quality:
"ollama/*": { hard: 0.45 }