Configuration¶
deputy init writes ~/.config/deputy/config.toml (mode 600). Change the folder with
DEPUTY_HOME, or point at a file with DEPUTY_CONFIG. Traces go to ~/.local/state/deputy
(DEPUTY_STATE). Secrets never go in the file: use api_key_file (must be mode 600) or
api_key_env.
default_backend = "local"
auto_tune = "propose" # off | propose | apply, see "Tuning" below
auto_update = "notify" # off | notify | apply, see "Updates" below
routing = "auto" # off | auto, see "Routing" below
[[backends]]
name = "local"
base_url = "http://127.0.0.1:8080" # the server root; deputy calls /v1/chat/completions
model = "default" # sent in each request; llama.cpp ignores it
kind = "local" # local | hosted
api_key_file = "~/.config/deputy/key"
timeout_s = 600
max_tokens = 4096
extra_body = { temperature = 0.2 } # merged into every request
[policy]
# Commands a `command` check may run (argv prefixes, no shell). Empty = none.
allowed_commands = [["node", "--test"], ["python", "-m", "pytest"]]
command_timeout_s = 120
run_budget_s = 900 # the least time one delegation may take; 0 = no limit
Backends¶
Anything that serves the OpenAI chat API with tool calling.
| Server | base_url |
Notes |
|---|---|---|
llama.cpp llama-server |
http://127.0.0.1:8080 |
start it with --jinja so tool calls work |
| Ollama | http://127.0.0.1:11434 |
model = the Ollama model name |
| LM Studio | http://127.0.0.1:1234 |
enable the local server |
| vLLM | http://127.0.0.1:8000 |
--enable-auto-tool-choice |
| Hosted (OpenAI-compatible) | the provider's root | kind = "hosted", key via api_key_env; your files leave the machine |
Several backends can be listed; pick one per call with the backend argument.
Profiles¶
A profile is a markdown file with a short front matter and the instructions the worker follows.
Bundled: helper. Add your own in ~/.config/deputy/profiles/ (yours) or .deputy/profiles/
(per project; the project wins). See
examples/project-dev.md
for a template.
The front matter can set the profile's limits:
---
name: strict-reader
description: Reads and reports, no second chances
max_turns: 4 # 1 to 50: the most tool turns the worker may take
max_retries: 0 # 0 to 5: correction rounds after a failed check (default 1)
---
max_turns: precedence, highest first: themax_turnsargument of the call, the profile's, the limit derived from the measured model profile, 8.max_retries:0means a failed check hands the task back at once (checks_failed,needs_frontier);2allows up to two correction rounds, each with the exact failure, and stops as soon as the checks pass. Without it, one correction round, as before.- A value that is not a whole number, or is outside its range, is ignored (the default
applies) and
deputy doctorsays which profile and why.
Policy¶
The orchestrator may declare command checks, but they only run if the argv starts with an entry
of allowed_commands. The worker model never runs anything.
Time budget. A delegation that runs out of time stops with turn_limit and the flag
time_limit, so a stuck model never blocks your agent. The budget is meant to stop a hang, not a
slow model: it is run_budget_s (900 s by default) or 20 times the time this model was measured to
need per task on your machine (deputy bench), whichever is larger. A model measured at 300 s per
task gets 6,000 s. Set run_budget_s = 0 for no limit. For a slow local model, delegate with
wait=false and collect the result later, so your agent keeps working meanwhile.
Tuning¶
deputy bench measures the model you configured; deputy tune also tries a few request-level
settings and recommends the best one that loses no accuracy.
deputy bench # one pass of the built-in suite, prints a table, saves a model profile
deputy bench --runs 3 # repeat: you get the spread too, and a fairer comparison
deputy bench --json # the same, as JSON for scripts and reports
deputy bench --run-code # also tasks whose grader runs model-written code (temp dir, 30 s)
deputy bench --slow # also the huge-file task (140 KB, minutes on a local model)
deputy tune # baseline + candidates; recommends, or applies per `auto_tune`
deputy tune --apply # write the winner to tuned.toml now
deputy tune --revert # undo the last applied tuning
auto_tune decides what deputy tune may do alone: off changes nothing, propose (default)
prints the recommendation, apply writes it. Applied settings go to tuned.toml next to your
config, never into your config; they overlay the backend's extra_body and max_tokens, and
deleting the file undoes them. A candidate is chosen only if it keeps pass rate and citation
accuracy and is faster than the measured spread or uses at least 15% fewer output tokens.
When the served model changes. deputy doctor compares the model the server answers with the
one that was measured. With auto_tune = "propose" or "off" it only says what to do. With
"apply" it runs one quick tune (four tasks, one pass, one of them held out) and writes the new
profile and any confirmed winner. This happens only in doctor, never during a delegate call,
because it takes minutes. A model that was never measured is not re-tuned.
Server flags (context size, thinking budget, cache) are outside deputy's reach: when thinking
dominates the time, tune prints the flag to try instead of changing anything. Custom candidates:
deputy bench --variant 'name={"extra_body":{"temperature":0.1},"max_tokens":512}'.
Language¶
Everything deputy ships (code, documentation, messages and the bundled profile) is in English, and
the bundled helper profile makes the worker answer in English. A custom profile can say otherwise.
Updates¶
deputy never phones home with your data. The only request it makes is a GET of the public "latest release" of this repository, at most once a day (cached; one hour after a failure).
auto_update = "notify"(default):deputy doctorand thestatustool say when a newer release exists. Nothing is installed.auto_update = "off": no request at all.auto_update = "apply": at server start, a newer compatible release is installed (same major version; while the major is 0, the same minor too, because a new 0.x minor may break things). A new major version is never installed without you. The new version runs from the next start.
deputy update --check only looks; deputy update upgrades now.
What an update does. It downloads the released wheel, checks where it was built, and only then installs it:
- the wheel is fetched from the GitHub release (and refused if it is far larger than a deputy release);
- its build provenance is verified with
gh attestation verify: the release workflow of this repository attests every wheel, so a match proves it was built there from a tagged commit and was not swapped afterwards; - if the check fails, nothing is installed, always;
- if the check cannot be done (the GitHub CLI
ghis missing or not logged in), a manualdeputy updategoes ahead and says plainly "provenance NOT verified" and why; add--require-verifiedto refuse instead. An automatic update (auto_update = "apply") always requires verification: with nobody watching, it installs only what it could verify.
You can go back to any release with DEPUTY_REF=<tag> sh install.sh. The installer itself does not
verify provenance; to check a release by hand: gh release download <tag> -R tommasomarchionni/deputy
then gh attestation verify <file>.whl -R tommasomarchionni/deputy. Each release also carries the
provenance bundle as <file>.whl.intoto.jsonl, so the check works offline too:
gh attestation verify <file>.whl --bundle <file>.whl.intoto.jsonl -R tommasomarchionni/deputy.
Usage report¶
Every run and every feedback is recorded in ~/.local/state/deputy/runs.jsonl (metadata only: no
file content, no answers, no secrets). deputy stats turns it into a report:
deputy stats # the last 30 days
deputy stats --days 7 # a different window
deputy stats --json # for scripts
deputy stats --include-bench # also the synthetic benchmark runs
It shows runs, the share that passed their checks (ok), how many were handed back to the
orchestrator (esc), how many needed a retry, the acceptance rate from your feedback, and the
estimated tokens saved (total and per run), for everything, by profile, and by task class (the
profile and the kinds of checks asked for, for example helper:cites_lines+contains). The status
tool carries a one-line version of the last 7 days.
Runs started by deputy bench and deputy tune are tagged source: bench in the trace and left out
of the report by default, so it describes real work; older trace lines without a source count as real
use (delete runs.jsonl for a clean start).
How the saving is estimated¶
For each delegation deputy estimates two things with the same yardstick: what the worker read on the
orchestrator's behalf (read: the lines it read, the hit lines a search returned, and the whole of
a file summarised by summarise_log or scanned by scan_file),
and what the orchestrator paid (cost: the request it wrote, serialised, plus the result it reads,
serialised). The saving is read - cost, and it can be negative: a task that reads little and
returns a lot costs more than it spares, and not_worth_delegating (tools) is built on
that. The trace keeps all three numbers; deputy stats shows the per-run read and cost.
The yardstick is the size in UTF-8 bytes divided by four, rounded up. It is the usual rule of thumb for English prose, and it is wrong by up to about a quarter either way: code and JSON are denser than this says, other languages vary. Because both sides use it, the difference is meaningful as an order of magnitude and a trend, not as an invoice. Not counted: the tool schemas the orchestrator carries for the session (about 970 tokens for all five tools, a fixed cost with or without delegation), and its own reasoning.
The measured model profile¶
deputy bench and deputy tune save what they measured for your model (pass rate, mean turns,
seconds, and the model name the server answered with) in ~/.local/state/deputy/models/, but only
after a run of the whole suite: a run limited with --tasks keeps the profile, because one task is
too noisy to set the turn limit and the time budget of every delegation. deputy
uses it in two ways:
- Turn limit. When a
delegatecall does not givemax_turns, the limit is the measured mean number of turns times two, between 4 and 12; without a profile it is 8. An explicitmax_turnsalways wins. A fast, reliable model gets a short leash; a slower one gets room. status. Next to each backend it shows<backend> profile: when it was measured and how it did, ornever measured: run deputy tune, or, when the server now serves a different model than the one measured, a note saying so and to rundeputy tuneagain.
Lessons learned from use¶
deputy learn reads the trace of your real runs (benchmark runs never teach) and looks for a
kind of check that keeps failing for a profile: at least 5 runs that carried it, and at least 25% of
them failing. For each one it proposes a lesson: a short reminder from a fixed catalogue (for
example, for contains: "list every fact the task asks for and make sure each appears"), with the
evidence behind it.
deputy learn # a report: what it would learn, and why
deputy learn --apply # save them; from now on they go into the worker prompt
deputy lessons # list the active lessons and what you muted
deputy lessons remove helper:contains # remove one, and never learn it again
deputy lessons check # test each lesson against the benchmark: with it and without it
deputy lessons check --apply # remove the ones that make the benchmark worse
deputy bench --lessons # measure the model with the lessons applied (default: without)
Rules that keep this safe: the text of a lesson comes only from the catalogue, never from a trace,
an answer or a file; at most 3 lessons are added to a prompt, only for the profile and the kinds of
checks the task asks for; a lesson expires after 14 days and is re-derived only while the evidence
still holds; workers cannot write lessons. Each run's trace records which lessons were applied, so
deputy stats and the benchmark can tell whether they help.
Optimising the worker profile¶
deputy optimise # measure, reflect, judge, confirm; writes a report, changes nothing
deputy optimise --list # saved proposals
deputy optimise --apply ID # your approval: installs it as your profile (previous one kept)
deputy optimise --revert ID # undo
Options: --profile NAME (default helper), --backend, --runs N (repeat each measurement).
A proposal is saved under the state directory with report.md (the tables and a diff). It can
only be applied if it also held up on the held-out tasks. A confirmed proposal's decision also states what it gains and
what it costs (pass rates, time per task, output tokens), and says so when it brings no gain on the
held-out tasks or is more than 25 % slower: confirmed only means it lost no accuracy. It takes minutes on a local model: it
runs the selection tasks for the current profile and for each proposal, then the held-out tasks.
Routing¶
With more than one [[backends]], delegate without a backend argument chooses one. Rules, in
order: never a more expensive or less private kind than the default backend (a local default only
uses local backends; a hosted default may fall back to local ones); local before hosted; measured
to pass (deputy bench or tune ran, at least 50% passed) before not measured before measured to
fail; the faster measured time first; then the default backend, then the order of the file. The
backends are probed (3 seconds) in that order: a silent one is skipped, and a run that ends in a
backend error moves on to the next. The choice and the reason are written to the trace as route.
routing = "off" always uses default_backend, with no fallback; naming a backend in the call
does the same for that call. With one backend nothing is probed and nothing changes.
Project memory¶
A small note per repository, so the worker knows where the rules live and what your words mean. Pointers, not copies: an entry says which file and why, so it cannot go stale.
deputy memory scan --apply # find AGENTS.md, CLAUDE.md, .github/instructions/*.md ...
deputy memory pointer docs/design.md "how stages are leased"
deputy memory term Lease "a hold on one worker stage"
deputy memory # show; `export` prints the same markdown to review in a PR
deputy memory remove Lease
--repo DIRpicks the repository (default: the current folder; a folder inside a repository is that repository).- The note lives in the state directory, keyed by the repository, never in the repository, and a worker cannot reach it.
- It is added to the worker's prompt only for tasks in that repository, capped at 1,500 characters (up to 12 pointers and 20 terms).
- A pointer must be a real file inside the repository and not a secret file.
Confinement of command checks¶
[policy] command_wrapper is an argv prefix that runs every command check inside an OS sandbox;
deputy init --confine writes one for your platform and deputy doctor reports whether commands
are confined. Details and what each platform allows: security.
Does a lesson help? deputy lessons check¶
A lesson is a bet, so it is tested. For each active lesson, deputy takes the benchmark tasks that
carry a check of the lesson's kind (a max_chars lesson: the tasks with a length limit), runs them
without the lesson and then with only that lesson (same model, same settings, --runs N
repetitions on both sides), and compares:
| Verdict | Meaning | What happens |
|---|---|---|
| helps | passes more or cites better with it | kept |
| neutral | no difference the benchmark can see (the suite may simply be too easy for it) | kept |
| hurts | passes less or cites worse with it (a loss on either counts) | listed; --apply removes it and mutes it |
| untestable | no benchmark task carries that kind of check | kept |
A real run on the local Qwen3.8 27B, a max_chars lesson, two repetitions:
pass 100% -> 100%, cites 100% -> 100%, tokens out 342 -> 209. The verdict is neutral (accuracy did
not change) and the report shows what it did change: 39% fewer output tokens. The report is the
point: you decide with the numbers in front of you. Use --runs 3 or more before trusting a close
call; the benchmark covers the kinds of check of its own tasks, so a lesson tested here is judged on
those, not on your real work.