Configuring docket: the files it creates and how to use them
This guide maps every file docket writes, on the machine and per project, to what it controls, how to change it, and what reads it while an agent is actually running. Its focus is the question the other guides leave open: how do I customize my agents, the orchestration between them, what they are allowed to do, and what of it leaves this machine?
Everything here was checked against a real install (docket init --pod full under a throwaway
HOME, then a real dispatch against a local model) and against the code on the live turn path.
When a file is written but nothing on the live path reads it, this guide says so. Several files
look like settings and are not.
Related: Agent Teams explains the pod model, Command Reference lists every flag, and its Environment Variables table lists every tunable. This guide links to both instead of repeating them.
Contents
- What an install creates
- How the files reach a running agent
- Customizing: recipes by use case
- File reference
- Sharp edges
1. What an install creates
docket init in a project directory does two things. The first time it runs on a machine, it
creates the workstation foundation (global state, shared org agents, baseline policies). Every
time it runs, it creates one pod for the current project. There is no separate setup step.
docket init stops before creating the pod unless a model endpoint is ready. On a fresh machine,
register one first:
docket models provider add local http://127.0.0.1:8081/v1 --model qwen \
--ctx 16384 --max-tokens 4096
docket models preset local # every role now resolves to local/qwen
docket init --pod full # Lead + Implementer + Reviewer + Tester
The result, with the moment each file appears. Files are 0600 and directories 0700 unless
noted.
~/.docket/ DOCKET_HOME: every piece of docket state lives here
├── fleet.json init agent registry, bindings, flags
├── docket-providers.json provider add your kind: provider documents (built-ins ship in the wheel)
├── docket-models.json init/preset role -> model policy
├── port-allocations.json first pod per-pod port range bases
├── audit.log first change hash-chained record of every mutation
├── policies/*.yaml init 6 baseline guardrail policies (JSON also loads)
├── docket-roles.json roles add your custom role archetypes
├── docket-mcp-servers.json mcp servers external MCP tool servers
├── docket-exporters.json exporters your kind: exporter overrides (built-ins ship in the wheel, all off)
├── exporters-health.json first export delivery counters per enabled exporter
├── docket-channels.json channels your kind: channel overrides (built-ins ship in the wheel, only console on)
├── channels-health.json first notify delivery counters per enabled channel
├── notify-state.json first notify the dedupe snapshot `docket notify flush` diffs against
├── inbox-cursor.json inbox the last `docket inbox` call's cursor (skipped by --peek/--since)
├── docket-schedules.json pod config dispatch schedules (`pod config set schedule`)
├── secrets.json, secrets.meta.json keys add stored API keys + timestamps
├── docket-runs.json dispatch one record per dispatch invocation
├── docket-conversations.json wire Telegram conversation registry
├── sessions/<session-key>/session.json dispatch durable per-session turn history
├── traces/<pod>/<session>.jsonl dispatch observable events per session
├── approvals/<apr-id>.json gated call pending/granted/denied approvals
├── consult-parked/<q-id>.json consult a parked question, until dispatch reads it
└── workspaces/
├── manager/ knowledge/ security/ init shared org specialists
├── projects/<pod>-<role>/ init/pod add one private workspace per pod member
│ ├── .docket-meta.json the agent's facts and per-pod settings
│ ├── SOUL.md identity and role instructions
│ ├── AGENTS.md red lines (and a startup section, see §2)
│ ├── TOOLS.md implementers only: ports, scratch dir, verify gate
│ ├── HEARTBEAT.md task ledger
│ ├── MEMORY.md durable project facts
│ ├── WORKFLOW_AUTO.md startup contract (versioned, regenerated)
│ ├── memory/YYYY-MM-DD.md daily logs
│ ├── TASK_LIST.json Lead only, after the first `delegate`: the pod's queue
│ └── tasks/<taskId>/ implementers in a git repo: one git worktree per task
└── pods/<pod>/.scratch/ first pod the pod's isolated scratch directory
Inside your repository, docket writes almost nothing, but not nothing. docket add and init
create no worktree; each task of a pod whose codebase is a git repository gets one when it is
claimed:
- a branch
docket/<pod>/<taskId>, created in your repo from its HEAD at that moment; - an entry under
<repo>/.git/worktrees/; - a checkout of that branch at
~/.docket/workspaces/projects/<pod>-implementer/tasks/<taskId>/, recorded on the task asworktree(dir,branch,baseCommit).
The Implementer edits that worktree, never your checked-out branch. Dispatch never commits: unless
the agent ran git commit itself, its changes stay uncommitted in the worktree, so you see them with
git -C ~/.docket/workspaces/projects/<pod>-implementer/tasks/<taskId> diff, then commit on its
branch and merge it like any other. Your verify command's by-products (__pycache__/, caches) land
there too. Finished task worktrees stay until you prune them: docket pod <pod> worktrees prune
(--dry-run first) removes each finished task's worktree whose branch is merged and whose tracked
files are clean, deletes the merged branch, discards untracked by-products and names every task it
keeps; --force also removes unmerged or edited ones (keeping the unmerged branch). A failed task
dispatch --resume would re-claim is always kept. docket delete removes them all with the member
and deletes the merged task branches (an unmerged branch is kept, with the removal command printed).
An Implementer marked inPlace works in the codebase itself and gets no task worktree. Reviewer and Tester run with the codebase root as
their working directory, so a test run can leave caches in your checkout.
To try any of this without touching your real setup, point HOME (or DOCKET_HOME) at a scratch
directory. Every docket path resolves under it.
2. How the files reach a running agent
This is the model you need to customize anything. Every live turn, whether a dispatch hop, a
docket serve sweep or a Telegram /delegate, rebuilds the agent's system prompt from disk.
Nothing is cached, so an edit takes effect on the next turn with nothing to restart.
The system prompt is, in this order:
SOUL.md, with the persona block re-rendered from.docket-meta.json. An oversizedSOUL.mdis visibly middle-truncated rather than starving the sections below.- A fixed runtime contract written by docket (not a file). It lists the directories the agent's tools may touch and tells it that its private workspace files are read-only.
- Workspace state, in this order:
HEARTBEAT.md,AGENTS.md,TOOLS.md,MEMORY.md. HEARTBEAT.mdis included from its first##heading on, with HTML comments removed.AGENTS.mdis included without its## Session Startupsection.TOOLS.mdandMEMORY.mdare included verbatim.
Section 3 shares one budget, resolved per turn from the model actually being called: half the
registered context window (minus the output reserve and a labelled tool-schema allowance),
floored at CONTEXT_TOKEN_BUDGET (default 6000) × CONTEXT_BYTES_PER_TOKEN (default 4) ≈ 24 KB.
A 16k local endpoint resolves below that floor, so it gets exactly the floor; a 200k hosted model
fits every section in full. Setting CONTEXT_TOKEN_BUDGET explicitly overrides both. The
prompt_composed trace event names the resolved budgetTokens and its budgetSource
(env/window/default). An oversized SOUL.md is capped (middle-truncated with a visible
marker) so it cannot crowd out the contract or the state sections; a state file that does not fit
is truncated or omitted with a one-line marker in the prompt naming it, and every composition
emits a prompt_composed trace event listing each section as full, truncated or omitted
(docket trace). Nothing is dropped silently. docket maintain <id> check warns when the static
context passes the budget.
Not sent to the model, despite what the file names suggest:
| File | What it is actually for |
|---|---|
WORKFLOW_AUTO.md |
The startup contract for an agent reading its workspace by hand. A live turn replaces it with the runtime contract above. Editing it changes nothing a docket turn sees. |
memory/YYYY-MM-DD.md |
Input to docket maintain distill (and to clean/reset, which distill first). Not in the prompt. Distill to move its content into MEMORY.md, which is. |
workflows/*.yaml in a workspace |
Nothing reads it. Pipelines are passed with --file or bound with pod config set pipeline (see §3.5). |
Who decides what: the ownership map
Six layers make up the orchestration, and each answers exactly one question. When you are unsure
where a change belongs, find the question first. Scope is which of the three provenance
levels a resolved value can come from — built-in (shipped, unwritable), global
(~/.docket/, every pod), or pod (this pod's own config/ directory, nearest-wins above
global) — the same three docket config explain <agent> --json labels per value.
| Question | Layer | Scope | Lives in | Change it with |
|---|---|---|---|---|
| What needs doing? | Task | pod | the Lead's TASK_LIST.json |
docket pod <p> delegate |
| Which team shape does a new pod get? | Blueprint | pod (creation-time only) | Lead meta blueprint |
docket init --blueprint |
| Who works a task, in what order, behind which quality gates, with how much rework? | Pipeline | global | pod | the blueprint's built-in default; a YAML file for a custom route, run once or bound as the pod default | docket pipeline validate/plan/run, docket pod <p> config set pipeline |
| How does each kind of agent behave, and which tools is it structurally denied? | Role archetype | built-in | global | pod | built-ins + ~/.docket/docket-roles.json + this pod's own config/roles.json |
docket roles [--pod <p>], docket pod <p> add <role> |
| What does this agent know about this project? | Workspace instructions | pod (per-agent) | SOUL.md, TOOLS.md, MEMORY.md; operator-owned INSTRUCTIONS.md (never regenerated); the codebase root's AGENTS.md by default, or the files projectInstructions names |
docket edit; edit INSTRUCTIONS.md directly; pod config set projectInstructions CONTRIBUTING.md |
| What is forbidden or human-gated, across everything? | Policies + command classifier | global | pod | ~/.docket/policies/*.yaml|json + this pod's own config/policies/*.yaml|json (+ fixed SAFE_BINS) |
docket policies [--pod <p>] |
| What budget, timeouts, approval posture, extra allowed commands, tool/MCP-server denials and verify gate bound this pod? | Pod settings | pod | the Lead's / member's .docket-meta.json |
docket pod <p> config get/set/unset (budgetUsd, maxReworkCycles, turnTimeoutS, verifyTimeoutS, approvalMode, approvalExpiryHours, inputExpiryHours, requireVerify, maxConsultationsPerTask, network, allowCommands, pipeline, schedule, projectInstructions, mcpServers, deniedTools); set-verify |
A pod's own overlay lives at ~/.docket/workspaces/pods/<pod>/config/ (docket.config.pod_config_dir(project)) — roles.json (same shape as the global docket-roles.json) and policies/*.yaml|json (same shape as the global policy store), each resolving above the global layer for that pod alone, never shared with any other pod. docket doctor flags a malformed entry in either file, naming the pod.
Two boundaries worth stating because they are easy to get backwards:
- The pipeline is the route and its controls, never the instructions. A step says who runs and how the output is judged (mechanical exit code, verdict marker, human approval). What the agent is told comes from its role template and workspace files (§2), plus the task text.
- Every pod always has a pipeline.
docket pod <p> dispatchruns the blueprint's default with no setup. For a custom route:docket pipeline validatechecks a file,planshows it against the real roster without spending tokens,run --fileexecutes it once by hand, anddocket pod <p> config set pipeline <file>binds it as the pod's default for every trigger (dispatch, serve sweep, schedules, webhooks, MCP). Binding validates and plans the file first, stores a docket-owned copy with its hash, and a later hash mismatch refuses dispatch loudly.docket pipeline plan <p>prints aSource:line naming which route would run.
The task itself arrives as the turn's user message, built by dispatch: the task description,
an instruction line, and the previous hops' output trimmed to the role's tokenBudget. The
instruction is, in order of precedence: the pipeline step's own instructions (which may
interpolate declared ${variables}, fed by docket pipeline run --var key=value or the webhook
body), the built-in role's hardcoded line, or a custom role's hopInstruction (declared, or
generated from its gateContract so a verdict role always knows its marker). Workspace files are
not re-read into it.
Private means read-only for the agent. The generated SOUL.md, AGENTS.md and
WORKFLOW_AUTO.md tell an agent to write its plan into HEARTBEAT.md and its day into memory/.
In a docket turn it cannot. Its tools are confined to the codebase (or worktree, or workdir), and
the runtime contract forbids touching private files. Durability comes from docket instead: session
history in sessions/, and a docket-owned region in the Lead's HEARTBEAT.md that dispatch
rewrites at every claim, hop and finish. That prose exists for an agent operating the workspace
outside a docket turn. You are the one who edits these files.
3. Customizing: recipes by use case
3.1 Choose which model each agent runs on
Three layers, from broad to narrow:
| Goal | Command | File written |
|---|---|---|
| Register an endpoint (OpenAI-compatible) | docket models provider add <file.yaml> (a kind: provider document), or the shortcut docket models provider add <name> <base-url> [--model ID] [--ctx N] [--max-tokens N] [--credential NAME] |
docket-providers.json → providers |
| List every provider | docket models provider list |
— (read-only) |
| Show one provider's resolved entry and scope | docket models provider show <name> [--json] |
— (read-only) |
| Remove a global override | docket models provider remove <name> |
docket-providers.json → providers |
| Print or write a provider as a document | docket models provider export <name> [<file>] |
the given file, or stdout |
| Point every role at one provider | docket models preset <anthropic\|openai\|google\|openrouter\|openrouter-free\|ai-gateway\|local> |
docket-models.json |
| Change one role's model | docket models set <role> <provider/model> (or set default …) |
docket-models.json → roles |
| Pin one agent, ignoring policy | docket profile <agent-id> <provider/model> (default un-pins) |
that agent's .docket-meta.json → model, modelSource: pinned |
| Store the API key | docket keys add OPENROUTER_API_KEY (or docket keys setup) |
secrets.json |
The model an agent actually calls is the model in its own .docket-meta.json. Policy changes
rewrite that field on every agent whose modelSource is policy, immediately. Pins are never
touched.
--ctx and --max-tokens matter: they are the limits docket checks requests against. Against a
small-context local server, also export DOCKET_TOOL_MAX_OUTPUT_CHARS=2500 (the 30000 default
suits a large hosted model, and two full tool results overflow a 16k window).
Credential lookup order, per name in the provider document's auth.credentials:
DOCKET_LLM_API_KEY, then that name as an environment variable, then the same name in
secrets.json. A document never holds a credential value — only names. DOCKET_LLM_BASE_URL
overrides every endpoint at once, which is handy for tests. docket config explain <agent>
--json reports which provider, scope and credential source an agent actually resolved to
(model-profiles.spec.md, "Provider catalog").
3.2 Change what an agent is told
Edit the agent's workspace files directly. docket edit <agent-id> opens them in $EDITOR.
| To change… | Edit | Notes |
|---|---|---|
| Role instructions, scope, tone, house rules | SOUL.md |
Always sent in full. The highest-leverage file. |
| Project commands, conventions, where things are | TOOLS.md (create it for non-implementers) |
Sent verbatim. The Implementer's is generated. See the caution below. |
| Durable facts about the product | MEMORY.md |
Sent last, so it is the first thing dropped when the budget is tight. |
| Red lines shared by a role | AGENTS.md |
Everything except ## Session Startup is sent. |
| What the repository tells every coding agent | AGENTS.md at the codebase root |
Read by default when projectInstructions is unset, screened as untrusted (§3.12). |
| Display name | docket persona <id> set "Rita" |
Written to meta and rendered between <!-- docket-persona:begin/end --> in SOUL.md. Never edit that block by hand. |
What overwrites your edits:
docket pod <p> add <role>writes a new member'sSOUL.md,AGENTS.md,HEARTBEAT.mdand (for an Implementer)TOOLS.mdfrom its role template. Existing members are not touched.docket pod <p> set-verifyregenerates the Implementer'sTOOLS.md. Put your own Implementer notes inSOUL.mdorMEMORY.mdinstead, or re-add them after changing the verify command.docket maintain <id> resetresetsHEARTBEAT.mdand clearsMEMORY.md(after distilling into it).cleandeletesmemory/*.md(after distilling).docket doctorrewritesWORKFLOW_AUTO.mdwhenever its contract version is stale. That costs nothing, since the file is not sent to the model.docket maintain <id> rebuildrefuses pod members and specialists, so it will not clobber them.
To change the instructions of every future member of a role, define a custom role (§3.4).
Existing members keep the SOUL.md they were provisioned with; there is no re-render command, so
edit those by hand.
3.3 Configure a pod: verify gate, budget, rework, timeouts
Pod-wide settings live in the Lead's .docket-meta.json. The verify command lives on the
member it gates.
| Setting | Key and file | How to set it | Effect |
|---|---|---|---|
| Verify gate | verifyCmd in the Implementer's meta |
docket pod <p> set-verify <p>-implementer "pytest -q", or --verify on docket init/pod add |
Runs after every Implementer hop in its worktree. A non-zero exit fails the task (verification_failed). |
| Budget cap (USD, estimated) | budgetUsd in the Lead's meta |
docket profile <p>-lead --budget 5 (0 = none) |
Checked before each hop. Over the cap, the task is blocked and the Lead paused until docket profile <p>-lead --resume. The figure is an estimate, not your bill. |
| Rework cycles | maxReworkCycles in the Lead's meta |
docket pod <p> config set maxReworkCycles 2 |
How many times a Reviewer REQUEST-CHANGES sends work back (default 1, 0 = none). Ignored when you run a pipeline file, which carries its own maxCycles. |
| Hop timeout | turnTimeoutS in the Lead's meta |
docket pod <p> config set turnTimeoutS 900 |
Per-hop wall clock (default 300 s). --timeout on dispatch overrides it for one run. Under docket serve, DISPATCH_TURN_TIMEOUT_S overrides it. |
| Verify timeout | verifyTimeoutS in the Lead's meta |
docket pod <p> config set verifyTimeoutS 300 |
Same precedence, DISPATCH_VERIFY_TIMEOUT_S under serve. |
| Retries | environment only | DISPATCH_RETRIES_DEFAULT, DISPATCH_RETRIES_<ROLE>, DISPATCH_RETRY_BACKOFF_S |
Timeouts and transport errors only. A failed verify or a bad verdict is never retried. |
| Pod roster | members' workspaces | docket pod <p> add <role> [--count N] / docket pod <p> remove <id> |
Dispatch only runs the roles the pod has. |
docket pod <p> config set <key> <value> validates before writing and is audited as
pod.config; config unset restores the default. A hand-edited value that fails validation is
not ignored: config get and dispatch both refuse, naming the key. Confirm with
docket pipeline plan <p>, which prints the resolved rework budget and steps.
{
"role": "lead",
"budgetUsd": "5",
"maxReworkCycles": 2,
"turnTimeoutS": 900,
"verifyTimeoutS": 300
}
(These are the relevant keys only. Keep the rest of the file as docket wrote it.)
3.4 Define a custom role
Roles are data. A role archetype carries its SOUL.md/AGENTS.md templates, the model class it
resolves to, the tools it is denied, its gate contract and its context budget. Built-ins (lead,
implementer, reviewer, tester, plus researcher, analyst, writer, critic, operator,
monitor) cannot be edited, only shadowed by name. See all of them with docket roles list, and
dump one as a starting point with docket roles show reviewer.
# security-reviewer.yaml — the short form; `docket roles show reviewer` dumps the canonical
# form this normalizes to (role-archetypes.spec.md, "Wire format")
kind: role
name: security-reviewer
description: read-only security pass over the implementer's change
model: strong # cheap | strong -> resolved through docket-models.json
cannot: [write, edit, bash] # the only enforcement field
verdict: [APPROVE, REQUEST-CHANGES] # or verify: true | approval: <message> | nothing
instructions: security-reviewer.md # default: <name>.md next to this file
# security-reviewer.md
# SOUL.md — ${project} · ${role}
You are the **${role}** of the **${project}** pod (agent id `${memberId}`).
Codebase: ${codebaseOrConfigured} (stack: ${stack}).
## Role — Security reviewer
- Review the change for injection, secrets in code, unsafe deserialization and authz gaps.
- You are read-only. Start exactly one line with `APPROVE` or `REQUEST-CHANGES`.
## AGENTS
# AGENTS.md — ${project} · ${role}
## Red Lines
- Stay within the `${project}` pod. No cross-project access.
docket roles validate security-reviewer.yaml # checks fields and dry-renders both templates
docket roles add security-reviewer.yaml # -> ~/.docket/docket-roles.json
docket pod myapp add security-reviewer # provisions myapp-security-reviewer
Template variables: project, role, memberId, sessionKey, objective, codebase,
codebaseOrConfigured, codebaseOrIt, stack, workDir, requiredStartupFile. An unknown
${var} fails validate.
What is read when:
- The instructions file (
soulTemplate/agentsTemplatein the canonical form) andmodelare used once, when a member is provisioned. Changing the overlay later does not touch existing members. cannot,tokenBudgetand the gate (verdict/verify/approval) are read live on every hop, from the merged registry.- A custom role gets no built-in per-hop instruction line, so everything it must do belongs in its instructions file.
- The default pipeline only runs
lead → implementer → reviewer → tester. A custom role joins a dispatch only through a pipeline file (§3.5).
3.5 Change the orchestration: pipelines and blueprints
Blueprints pick a pod's shape at creation: docket init --blueprint
software|research|content|ops|agentic-product. Only these five exist, and the choice is stored as
blueprint in the Lead's meta. Dispatch uses the blueprint's built-in pipeline.
Pipeline files declare your own hop order, gates and rework edges. This one runs the custom role
from §3.4, in the short form — docket pipeline validate normalizes it to the canonical form
pipeline-format.spec.md defines, which is what plan/run actually execute:
# pipeline.yaml
kind: pipeline
name: build-then-security
description: Lead plans, Implementer builds (verify-gated), security reviewer vets with rework
steps:
- plan: lead
- build: implementer
timeout: 900
verify: true # -> gate: {type: mechanical} (member's own verifyCmd)
- vet: security-reviewer
verdict: [APPROVE, REQUEST-CHANGES] # first marker passes; the rest can trigger `on:`
on: {REQUEST-CHANGES: {goto: build, max: 2}}
docket pipeline validate pipeline.yaml # structure only, no pod needed
docket pipeline plan myapp --file pipeline.yaml # resolves against the real roster, runs nothing
docket pipeline run myapp --file pipeline.yaml # executes; same budget/gates/traces/runs as dispatch
Short form (unknown keys are rejected at every level; pipeline-format.spec.md, "Short form",
"Outcome routing", "Conditional steps and command steps" define the full mapping and canonical
form):
- Top level:
kind: pipeline,name(required),description,variables,steps. - Each step: one
<id>: <role-or-agent>key, plus optionaltimeout,retries,instructions, and at most one ofverify/verdict/approval(the gate) oruntil+max(a bounded mechanical self-retry). - Gate sugar:
verify: true(or a command string) for a mechanical gate;verdict: [...]for a verdict gate, first marker passing;approval: "<message>"for a human sign-off (the task waits inwaiting_approval). No sugar key at all falls back to the role's own gate. on: {<label>: {goto: <step>, max: <n>}}routes any named outcome — not only a verdict's rework — to an earlier or later step,fail, orstop; a backward or self target requiresmax.when:(changed,var+is,memberPresent) skips a step; a command step (- lint: {run: "ruff check ."}) runs no agent turn at all, its exit code and last stdout line becoming its outcome.
One rule to plan around: a bound pipeline (pod config set pipeline) is treated like a
caller-supplied --file — the pod's maxReworkCycles setting never patches it, so the file's own
rework edges are what run. Only the blueprint/built-in default is patched by that setting.
3.6 Govern what agents may do
Every tool call passes one chokepoint that applies, in order:
- The role's tool denials.
- The argument-aware high-risk command classifier. It is always on and not configurable.
- Your policies.
Tool denials (per role). The built-in tools are read, glob, grep, fetch (read kind),
write and edit (write kind), and bash (exec kind). MCP tools arrive as
mcp__<server>__<tool> and carry the kind their server declares (docket mcp servers add --kind
read|write, default write; --tools a,b limits which of its tools register).
- Denying a tool also denies every tool of its kind. That is how a read-only role gets no MCP tools from a server left at the default kind.
- Built-in denials:
lead,reviewer,critic,monitor:write,edit,bash.tester:write,edit.- Denials are per role, plus an optional per-pod list:
docket pod <p> config set deniedTools fetchremovesfetchfrom every role of that pod. To restrict one agent, give it a custom role.
Shell commands (the curated allowlist). A bash call runs unattended only when every
segment's binary (behind ;, &&, || and pipes) is on a fixed list and no high-risk class
matches. Anything else asks a human.
- On the list:
ls cat head tail wc sort uniq cut tr nl grep egrep rg fd find file stat tree realpath dirname basename sed awk jq yq diff comm git node npm npx pnpm yarn python3 pip pip3 go cargo rustc make cmake date env printf which xargs tee less mkdir touch cp mv ln, plus the side-effect-free builtinscd pwd echo true false test [. A redirectedecho(>,>>,&>) still asks. - Not on the list, so each one asks:
pytest,python,uv,bash,rm,export,source. - Per-pod widening, scoped and audited:
docket pod <p> config set allowCommands pytest,uvadds exact binary basenames to the allowlist for that pod's turns only. Paths, shell metacharacters, opaque names (eval,source, …) and high-risk-class bins (git,npm) are rejected at write time; a redirected call still asks. Policies remain stricter-only: anallowpolicy cannot loosen the classifier. - In an unattended run today, an ask does not block at all by default:
serve --dispatch's sweep and a non-interactivedocket pod <p> dispatchboth resolve an unsetapprovalModetopark(§3.15) — the first ask records the call and parks the taskwaiting_approvalimmediately, ending the turn rather than eating a 120-second wait. An explicitapprovalMode: wait(or an interactive foreground TTY, which still defaults towait) keeps the older behavior: each ask blocks the turn forTOOL_APPROVAL_TIMEOUT(120 s) and is then denied, and after three denials in a row (AGENT_LOOP_MAX_CONSECUTIVE_TOOL_DENIALS) the hop fails. For a pod that should never wait or park — a CI job with no one to grant it later — setdocket pod <p> config set approvalMode refuse: a gated call then fails the hop immediately withapproval_unavailable, naming the tool and policy. - This is not hypothetical. Verifying this guide (pre-Phase-34, under the always-
waitbehavior), a real dispatch passed Lead, Implementer and Reviewer, then failed the task at the Tester on three asks. The asks were forcd <worktree> && python3 …, which W37-C1 has since allowed.pytestanduvstill ask — and today, an unattended run hitsparkon the very first one rather than accumulating three denials.
Three ways to avoid it:
-
Allowlist the bins for that pod.
docket pod <p> config set allowCommands pytest,uv(see above) is the direct fix for exactly this failure. -
Run checks through the verify gate. Put them in the mechanical gate (
set-verify, or a pipelinemechanicalgate). That command runs outside the tool classifier; only high-risk commands are refused there. - Use allowlisted forms. Add this to
SOUL.md: usepython3 -m pytestrather thanpytestoruv run pytest.bashalready starts in the agent's first project root (the worktree, for an Implementer), so relative paths work.
Policies (~/.docket/policies/*.yaml|yml|json, relocatable with POLICIES_DIR). Every file
in the directory is loaded, and all of them are re-read on every call, so a new file is live
immediately. Write the short form (the shipped templates under policies/ are examples);
core.policy.normalize_policy turns it into the canonical shape the evaluator actually reads —
see security-gates.spec.md, "Policy format v1" for that mapping and the canonical field names:
kind: policy
name: no-curl
appliesTo: [implementer]
when: {matches: '\bcurl\b'}
then: ask
message: curl needs approval
| Field | Values |
|---|---|
appliesTo |
Role names as dispatch sees them (implementer, reviewer, … or a custom role), or "*". |
on |
input (a task entering the queue; always evaluated as role lead), toolCall (tool name and arguments, the default), output (a hop's output). |
when |
tool, path (glob over a path/file argument), matches (regex over the rendered call, case-insensitive), branch (glob over the worktree branch), anyOf (OR over a list of the above); sibling keys AND. |
then |
allow, warn (record only), redact, ask (require approval), block (deny). There is no deny action; use block. |
How policies combine and what they ignore:
- Precedence. The most restrictive matching action wins:
block>ask>redact>warn>allow. - A broken policy fails closed. A file with bad JSON/YAML, an uncompilable regex or an
unknown action evaluates as
blockwithin its readable scope (the hook and roles it declares, or every hook and role when the file itself will not parse), attributed to the file so you know what to fix;docket doctornames it before a live turn does. After every edit, rundocket policies testwith a string the policy must match, for exampledocket policies test pre_tool_call implementer "make deploy", and confirm the expected result. redactuses docket's generic secret redactor, not your pattern.- Ignored fields.
descriptionis documentation only.
Extending with a predicate plugin. The closed when vocabulary above covers most policies;
for a check no built-in predicate expresses, ~/.docket/plugins/ (operator scope) or a pod's own
config/plugins/ (copied there by docket pod <p> apply, never read live from a codebase) can
hold a small Python file registering a named predicate, referenced as when: {plugin: <name>,
with: {...}} — then: still decides the action. Every predicate plugin is loaded only from
operator/pod scope (never the agent's own workspace), audited by name and file hash, and a
plugin that raises, times out, or returns a non-bool fails closed (deny), never open.
docket plugins list shows each one's name, scope, file and hash. See
ADR 0010 §4 for the trust boundary this is
built around.
Approvals. A require_approval hit, or a high-risk command such as git push origin main,
creates approvals/<id>.json.
- Answering. Answer it with
docket approve <token>/docket deny <token>,POST /approvals/<token>underdocket serve, MCP, or Telegram/approve. Every channel is audited. - Expiry. Unanswered requests are denied: after
TOOL_APPROVAL_TIMEOUT(120 s) when a live tool call is waiting, afterAPPROVAL_TIMEOUT(900 s) at a pipeline approval gate. - Harness mode.
docket harness runnever waits. It returnsapproval_unavailableinstead.
Network. fetch refuses every host until you allow it:
FETCH_ALLOWED_DOMAINS=docs.python.org,api.github.com. That makes fetch the inspectable
path; by default it is not the only one, since bash can still reach the network through
allowlisted interpreters. docket gates network none (or a pod's network setting) cuts the
jail's network, leaving fetch as the only path.
Isolation (opt-in). Off by default: tools run on the host. docket gates isolate on jails
bash and stdio MCP servers in bwrap (Linux) or Docker (Linux or macOS), and refuses to record
on when neither is usable; once on, a turn is refused rather than run unjailed if the backend
disappears. The Docker image is DOCKET_SANDBOX_IMAGE. The choice is isolationMode in
fleet.json; networkMode (docket gates network) is the other security flag the live path
enforces. Requirements and coverage:
SECURITY-SIMPLE.md.
3.7 Give agents external tools (MCP)
docket mcp servers add github --env GITHUB_TOKEN=... --timeout 20 -- npx -y @modelcontextprotocol/server-github
docket mcp servers list
The command writes docket-mcp-servers.json. Its tools appear in a turn as
mcp__github__<tool>, gated like built-ins.
- Declare the kind. A server is
--kind writeunless you say--kind read; nothing can prove a remote tool is read-only, so the declaration is your audited assertion. A role that denieswrite/edit/bash(§3.6) gets MCP tools only from a server declaredread.--tools a,blimits which of a server's tools register at all. - Servers are per install; a pod picks its own.
docket pod <p> config set mcpServers github,fslimits that pod to those servers (unsetrestores every configured one); a name absent from the catalog refuses dispatch loudly.docket pod <p> config set deniedTools fetchremoves a tool from every role of that pod. - Spawn cost. Each selected server is spawned once per turn, about 0.6 s measured.
- Plaintext env.
--envvalues are stored in plaintext; they are masked only inlist.
3.8 Run unattended
- Continuous sweep.
docket serve --dispatchdrains every pod's queue. Add--telegramfor the approval channel. A gated tool call an unattended hop hits doesn't block the sweep: it resolves toapprovalMode: parkby default (an explicit stored value always wins) and moves on — see §3.15 for parking, the derived inbox, and how a human answers. - Schedules.
docket pod <p> config set schedule "<spec>"validates and writes one (unset scheduleremoves it); an invalid spec is refused atset, and the serve sweep logs a line for any hand-edited spec it has to skip. Schedules fire only whileserve --dispatchruns:
json
{"schedules": {"myapp": "@every 30m", "otherapp": "09:00", "third": "*/15 9-17 * * 1-5"}}
- Formats.
@every Ns|m|h, a dailyHH:MMin UTC, or a numeric 5-field cron in UTC. - Skips are named. An entry docket cannot parse never fires; the
servesweep logs a line for it anddocket doctorreports it. - Don't add other keys.
serverewrites the file withlastRunand drops any other top-level key. - Webhooks. Use
POST /dispatch/<project>with the serve bearer token. SetDOCKET_SERVE_TOKENto make that token stable. - Telegram.
docket wire <p>-leadbinds a chat. It writesfleet.jsonbindingsanddocket-conversations.json.
3.9 Turn-loop limits
The per-turn stop conditions are all environment variables:
AGENT_LOOP_MAX_ITERATIONSAGENT_LOOP_MAX_TOOL_CALLSAGENT_LOOP_TOKEN_BUDGETAGENT_LOOP_WALL_CLOCK_TIMEOUT_SAGENT_LOOP_REQUEST_TIMEOUT_SAGENT_LOOP_MAX_CONSECUTIVE_TOOL_DENIALS
They apply process-wide, to every agent. There is no per-role or per-pod value. See the
Environment Variables table for defaults. For
docket serve, set them in its unit file or shell.
3.10 Start from a recipe
A recipe is a directory in the same shape as a repository's .docket/ (§3.11): pod.yaml,
roles/, pipeline.yaml, policies/, plugins/, skills/, every part optional. What a recipe
brings is derived from what the directory holds, never declared: docket validate <dir>,
docket pod <p> apply --dry-run, docket init --recipe and docket recipes show all print the
same summary line (roles 1 · policies 1 · members 1 · pipeline secure-build · ...). Eighteen
ship with docket, of five kinds; the full page, generated from the recipes themselves, is
the recipe library.
| Kind | Recipes | What apply plans on a lean pod |
|---|---|---|
| Team | secure-build, research-review, ops-approval, intake |
roles and members it needs, a pipeline, sometimes a policy |
| Policy pack | git-safety, no-egress, secrets-guard, prod-approval |
policy items only: no roster change, no pipeline change |
| Methodology | tdd, spec-first, spec-writer, reflexion, dual-review, cross-family-review, frugal |
the members the practice needs from the built-in and starter roles, and the smallest pipeline that is the practice (frugal also sets a budget) |
| Check | anti-tautology, mutation |
a pipeline with a run: step that fails the task when its tests prove nothing (mutation needs mutmut installed) |
| Tooling | code-intel |
MCP servers for the pod (structural search, read-only language intelligence) |
docket recipes list # every recipe reachable by name, what each brings
docket recipes show tdd # description, summary, the recipe's own README
docket init --recipe secure-build # a new pod for this repository, recipe applied after provisioning
docket pod myapp apply git-safety # a policy pack onto a pod that already exists
docket pod myapp apply ./team-recipes/ci # a directory of your own, same shape
docket pod myapp apply --dry-run # no argument: <codebase>/.docket/, plan only
A name resolves in three places, nearest wins: a directory path as given, then your own
~/.docket/recipes/<name>/, then the shipped library. Dropping a directory under
~/.docket/recipes/ makes it addressable from init --recipe and apply with no registration.
apply copies the directory's roles into this pod's own overlay (config/roles.json),
validates and binds its pipeline.yaml as the pod's default (§3.5), adds the members its
pod.yaml names, copies its policy pack into this pod's own config/policies/ (§3.6) and its
skills into config/skills/ (§3.13) — the same steps you would otherwise do by hand, scoped to
this pod alone, validated as a whole before anything is written. --dry-run shows the plan;
re-running is idempotent (an applied recipe plans every item skip). Every apply records the
directory as the pod's configSource (§3.11), the all-skip one included.
Compose, then commit. Recipes are seeds; the repository is where they combine. Apply the team you want, then the policy packs security asks for, then write the result back next to the code and apply that once so the record names the repo:
docket init --recipe tdd
docket pod myapp apply git-safety
docket pod myapp apply secrets-guard
docket pod myapp export --force # the merged team, in .docket/
docket pod myapp apply # plans every item skip; configSource is now ./.docket
git add .docket && git commit -m "Add: the myapp agent team"
Two pipelines applied in sequence replace each other (the plan says replace); policies and
roles accumulate. docket pod <p> export <dir> writes the reverse of apply: this pod's own
scope, in the same directory shape and the short form, with a # yaml-language-server: header
resolved against the config-v1 JSON Schemas it copies into <dir>/.schemas/ (the same schemas
scripts/gen_config_schemas.py publishes under docs/contracts/config-v1/).
3.11 Keep the team in the repo
A team is a directory named .docket/ next to the code, in the same shape docket pod <p>
export writes and every shipped recipe ships:
.docket/
pod.yaml kind: pod members (roles to add), settings, optional pipeline filename
roles/<name>.yaml kind: role short form: model, cannot, verdict|verify|approval, instructions
roles/<name>.md the role's instructions, plain Markdown
pipeline.yaml kind: pipeline short form: `- id: role` steps with verify/verdict/approval/on
policies/*.yaml kind: policy when/then; JSON still loads
plugins/*.py hashed predicate plugins (rare)
skills/<name>/SKILL.md Agent Skills: name + description up front, the body read on demand
.schemas/ generated JSON Schemas the `# yaml-language-server` headers point at
A complete, small one. pod.yaml names the members to add beyond the Lead + Implementer the
blueprint provisions, and any pod setting (§3.3, §3.6) to set; the other files are the same short
forms §3.4, §3.5 and §3.6 describe:
# .docket/pod.yaml
kind: pod
name: myapp
members: [security-vetter]
settings:
budgetUsd: 5
allowCommands: pytest,uv
approvalMode: refuse
# .docket/pipeline.yaml
kind: pipeline
name: secure-build
steps:
- plan: lead
model: cheap
- build: implementer
verify: true
- vet: security-vetter
verdict: [APPROVE, REQUEST-CHANGES]
on: {REQUEST-CHANGES: {goto: build, max: 1}}
roles/security-vetter.yaml and .md are the secure-build recipe's (export writes them after
init --recipe); a role of your own is the §3.4 example, and policies/no-curl.yaml the §3.6
one. The loop you run each time the team changes:
docket pod myapp export # first time: write what the pod has now into ./.docket/
$EDITOR .docket/pipeline.yaml # change the route, a rule, a role
docket validate # every document, invalid files first, exit 1 on any error
docket pod myapp apply --dry-run # the plan: add / replace / skip per item
docket pod myapp apply # write it (one pod.apply audit entry when something changed)
git add .docket && git commit # the team is versioned with the code
Three commands read it, and nothing else does:
| Moment | Command | What happens |
|---|---|---|
| Creating the pod | docket init (with .docket/ present) or docket init --recipe <name\|dir> |
every document is validated before the pod is provisioned (an error exits 1 naming file, line and field, and provisions nothing); after provisioning, the directory is applied exactly as pod apply would, with one pod.apply audit entry. --no-apply provisions only. --recipe and a present .docket/ together are refused: one source of record. |
| Re-applying after a change | docket pod <p> apply (defaults to <codebase>/.docket/) |
additive and idempotent: a second run plans every item skip; --dry-run shows the plan |
| Writing it back | docket pod <p> export (defaults to <codebase>/.docket/; refuses a non-empty one without --force) |
the pod's own scope in the short form, ready to commit |
Rules worth knowing:
- Nothing is applied without an operator command. Dispatch,
serve, schedules and the harness never read.docket/: an Implementer editing it in its worktree changes nothing until you apply it.docket config explain <agent>printsconfigSource,configDigestanddrift: yes|no, so you can see that the directory moved on since it was applied. - A repository cannot loosen your rules. Its policies land in the pod scope and accumulate
with the global ones under the most-restrictive rule; a global
blockstays a block. - A credential value never appears. Provider documents and policies carry names; keys live in
docket keys. - Validate from the repo root with
docket validate(no argument:.docket/when present). Commit.schemas/if you want editor autocompletion offline;exportregenerates it. - A step may name its model (
model: cheap|strong|<provider/id>): it applies to that hop only and is never written to the agent's own metadata, sodocket profilestill shows the persisted model.
3.12 AGENTS.md: the instructions your repository already keeps
Many repositories keep an AGENTS.md at the root for coding agents (Codex, Copilot, Cursor and
Claude Code all read it). docket reads it too, by default: when a pod's projectInstructions
setting is unset and the codebase root holds AGENTS.md, it is composed into every member's
system prompt as the project-instructions section, right after INSTRUCTIONS.md. It is treated
as content from the codebase, not from you: screened through the pre_input policy hook as
untrusted (a block replaces it with an audited one-line marker), middle-truncated to its budget
share, and reported as projectInstructions in the prompt_composed trace event.
docket config explain myapp-implementer # ... Project instr.: AGENTS.md (default)
docket pod myapp config set projectInstructions CONTRIBUTING.md,docs/STYLE.md # an explicit list replaces the default
docket pod myapp config unset projectInstructions # back to the default
An explicit list never adds to the default: name AGENTS.md in it if you want both. The
AGENTS.md docket writes inside each agent's private workspace is a different file (a role's
red lines, §2); the two are composed in different sections. Nested AGENTS.md files deeper in
the tree are not read: a turn has one root.
3.13 Skills: instructions an agent pulls on demand
A skill is a directory holding a SKILL.md in the Agent Skills shape: YAML front matter with
name (equal to the directory name, [a-z0-9-], up to 64 characters) and description (one
sentence, up to 1024 characters), then the instructions as Markdown, with optional
scripts/, references/ and assets/ beside it. docket looks in three places, nearest wins by
name:
| Scope | Directory | How it gets there |
|---|---|---|
| repository | <codebase>/.docket/skills/<name>/ |
committed with the code, read in place |
| pod | ~/.docket/workspaces/pods/<project>/config/skills/<name>/ |
a recipe's skills/ copied by apply; export writes it back |
| global | ~/.docket/skills/<name>/ |
you put it there, for every pod on this machine |
Disclosure is progressive, as the shape intends. The system prompt gets a # Skills section of
- name: description lines (each description screened through pre_input as untrusted, the
section capped and reported as skills), and the body is read only when the agent calls the
skill tool with a name (or a name and a file inside the skill's directory). That tool is a
built-in of kind read, goes through the same chokepoint as every other, and is denied per role
with cannot: [skill] like any other tool. A skill whose front matter is invalid (a name that
does not match its directory, a missing description) is skipped and audited once, never raised
into a turn. allowed-tools and other keys are accepted and ignored: a role's denials are the
only capability statement.
mkdir -p .docket/skills/release-checklist
$EDITOR .docket/skills/release-checklist/SKILL.md # front matter + the checklist
docket config explain myapp-implementer # ... Skills: release-checklist (repo), security-review (pod)
secure-build ships one (security-review, a concrete review checklist the vetter can pull);
tdd and spec-first ship test-first and writing-a-spec. Instructions from the repository,
AGENTS.md and skills alike, are read live and screened; rules from the repository (roles,
policies, pipelines, settings) are still applied only by an operator command (§3.11).
3.14 Export traces to OpenTelemetry or Langfuse
The record docket trace reads can also go to a tool you already run: an OpenTelemetry
collector, Jaeger, Phoenix, Honeycomb or Langfuse. A destination is a kind: exporter YAML
document, the same shape as a kind: provider (§3.1). Five ship in the wheel, all off:
otel-collector, jaeger and phoenix need no credential, honeycomb takes a header key and
langfuse a basic-auth pair. Credentials resolve as a provider's do, from the environment first
and then from docket keys add. Nothing is sent until you run docket exporters enable, and a
present credential never turns an exporter on by itself.
Every turn docket runs (a dispatch hop, a serve --dispatch sweep, docket harness run) hands
the records it writes to the local trace, already redacted, to core/telemetry.py, which turns
each session into spans: a docket.session root with gen_ai.chat and execute_tool children,
their ids derived from the session id so a re-send lands on the same trace. A pod dispatch runs
every hop in one session, so its lead, implementer, reviewer and tester appear as one trace, each
model call its own span, under one root that stays open from the first hop to the last. A background
pipeline delivers them to every enabled exporter as OTLP/HTTP JSON over the standard library
(the otlp-http dialect; D-24's cut of the OpenTelemetry SDK stands, D-48). It holds a bounded
queue, counts what it drops, and never raises into a turn. The pipelines start with the first
turn of a process and keep that set of exporters and levels for its life, so a change made with
the commands below reaches the next dispatch or harness run at once and a running
docket serve only after a restart. DOCKET_NO_EXPORT=1 turns export off for one process;
DOCKET_NO_TRACE=1 stops the local write and, with it, the export.
What leaves this host: the privacy level
Each exporter document declares what it shares beyond bare structure (ADR 0015). Structure — model and tool names, timing, measured token counts, pass/fail, ids — is always sent. Content is split into six classes, and a level is a named set of them:
privacy: |
Adds | The destination sees |
|---|---|---|
minimal (default, every built-in) |
nothing | structure only; Input/Output columns stay empty |
actions |
toolArguments, errors |
what the agent did: tool arguments (gen_ai.tool.call.arguments), an approval's command line, error text |
conversation |
+ toolResults, completions, prompts |
what was said and read: gen_ai.input.messages, gen_ai.output.messages, gen_ai.tool.call.result |
full |
+ instructions |
also the system prompt (gen_ai.system_instructions), sent once per session and again only when it changes |
Or name the classes exactly: share: [completions, toolArguments]. contentMaxChars (default
4000) cuts every content value, keeping JSON intact. The attribute names are the OpenTelemetry
GenAI ones, which Langfuse reads natively as a generation's Input/Output. Credentials and
secret-shaped values are redacted before anything is written, at every level.
Three rules keep the level honest. The projection is an allowlist: an attribute leaves only
when its class is granted, so a new trace field stays home until someone classifies it. A
conversation is filtered per part: sharing prompts sends your task and the model's text
but replaces a tool result inside it with {"type": "withheld", "class": "toolResults"}.
And content is captured only on demand: prompts, replies and tool output enter the local
trace only while some enabled exporter grants them, so at minimal everywhere the local trace
is exactly what it was without exporters.
Choosing a level
Widening is a command, not an edit you can make by accident. It lists what starts leaving and
where, and asks; off a TTY it refuses unless you pass --yes. Narrowing never asks. Both are
written to the audit log as exporter.privacy name=… from=… to=… host=…. Real transcripts from
this machine:
$ docket exporters privacy langfuse conversation
⚠ 'langfuse' will widen from 'minimal' to 'conversation':
+ toolArguments (e.g. gen_ai.tool.call.arguments)
+ errors (e.g. docket.error.message)
+ toolResults (e.g. gen_ai.tool.call.result)
+ completions (e.g. gen_ai.output.messages)
+ prompts (e.g. gen_ai.input.messages)
destination: cloud.langfuse.com
✗ Error: Refusing to widen 'langfuse' off a TTY without --yes.
$ docket exporters show langfuse
...
privacy conversation
Leaves this host:
✓ toolArguments (gen_ai.tool.call.arguments, docket.approval.action)
✓ errors (docket.error.message)
✓ toolResults (gen_ai.tool.call.result)
✓ completions (gen_ai.output.messages)
✓ prompts (gen_ai.input.messages)
✗ instructions (gen_ai.system_instructions)
never: credentials, secret-shaped values (redacted)
docket exporters preview <name> shows what a destination would receive from a real local
session (the newest, or --session <id>) before anything is sent: every span, every attribute
with its class, and a footer counting them. --level/--share try another level without
writing it; --json prints the exact wire document. It opens no socket and writes nothing.
Because content is captured only on demand, a session recorded at minimal holds no
conversation to preview at conversation; the footer says so rather than showing less than a
later session would send.
$ docket exporters preview langfuse
Preview: langfuse (session agent:harness-e262ed07e5a2:default)
privacy: actions shares: errors, toolArguments
execute_tool read
gen_ai.tool.name [structure] read
gen_ai.tool.call.arguments [toolArguments] {"path": "notes.txt"}
docket.tool.ok [structure] True
...
spans: 4
attributes:
structure: 21
toolArguments: 1
...
bytes: 2934
The level also travels with the data: every docket.session root span carries
docket.privacy and docket.privacy.classes, so the destination shows what it was allowed to
receive. From conversation up the root also carries the session's task and its last answer
(docket.session.input, docket.session.output); the built-in langfuse document aliases them to
the root observation's input and output, which Langfuse shows as the trace's own. docket exporters list has a SHARES column, docket config explain prints the level
per exporter, and docket doctor notes any exporter sharing conversation or full with a host
that is not this machine.
Turning a destination on
enable resolves the credential (a TTY prompt, or a refusal naming docket keys add <NAME>
when there is none), probes the endpoint with it, and classifies the result before writing
anything. A transport failure refuses the enable; a reachable-but-unauthenticated endpoint still
enables, because only a transport failure is disqualifying. enable --privacy <level> (or
--share a,b) sets the level in the same step, under the same confirmation rule.
$ docket exporters enable langfuse --privacy actions --yes
✓ Exporter enabled: langfuse -> https://cloud.langfuse.com/api/public/otel/v1/traces
scope: global shares: actions (errors, toolArguments)
$ docket exporters enable honeycomb # no key stored yet
✗ Error: Exporter 'honeycomb' needs credentials that are not set:
docket keys add HONEYCOMB_API_KEY
Store the missing credential(s) with docket keys add <NAME> (prompts, never take a value as an
argument) and re-run enable -- it re-probes with the stored credential before writing anything.
| Command | Effect |
|---|---|
docket exporters list [--json] |
Every built-in and global exporter, dialect, activation state, required credentials, scope, SHARES |
docket exporters show <name> [--json] |
One exporter's effective document, health counters (exported/dropped/failed) and the "Leaves this host" block |
docket exporters enable <name> [--endpoint URL] [--privacy <level>\|--share a,b] [--events ...] [--no-verify] [--yes] |
Resolves credentials, probes, writes a minimal global override (never the whole inherited document) |
docket exporters privacy <name> [<level>\|--share a,b] [--max-chars N] [--yes] |
Without a level, prints what leaves; otherwise changes it, confirming a widening |
docket exporters preview <name> [--session <id>] [--level <level>\|--share a,b] [--json] |
What the destination would receive from a local session; no network, no write |
docket exporters disable <name> |
Writes enabled: false to the override, nothing else |
docket exporters test <name> |
Re-probes the currently-configured endpoint without changing anything |
docket exporters add <file.yaml> [--yes] |
Registers a new kind: exporter document; one above minimal follows the widening rule |
docket exporters remove <name> |
Removes a global override; a built-in reverts to its shipped defaults instead of disappearing |
docket exporters export <name> [<file>] |
Writes the effective document back out, short-form YAML |
A pod names the destinations it wants in pod.yaml's exporters: list (validated against the
live catalog by apply/validate/init --recipe; unknown names refuse before anything is
written); the list is recorded and reported, never itself the thing that turns an exporter on --
docket exporters enable is still the one write that flips enabled: true, so naming a
destination in a recipe documents intent without silently starting to ship data anywhere.
# .docket/pod.yaml
exporters: [otel-collector, langfuse]
Live proof, this machine, 2026-09-28: one real docket harness run turn per level against
the local llama.cpp endpoint, with otel-collector (a local otel/opentelemetry-collector,
debug exporter) and langfuse both enabled at that level, a unique canary in the task and
another in the file the agent read. minimal: no canary in the collector log, in Langfuse, in
preview --json or even in the local trace; Langfuse's Input/Output empty. actions: tool
spans carried {"path": "notes.txt"}, still no canary. conversation: Langfuse showed each
generation's Input and Output and the read tool's result, both canaries present. Full detail:
specs/functional/observability-export.spec.md §"External verification".
3.15 Notify a human, and answer without blocking
An unattended pod's gated tool call used to have two choices: block the hop for up to
TOOL_APPROVAL_TIMEOUT (120s) with nobody watching, or approvalMode: refuse and lose the call
outright. A third posture, park (ADR 0016, D-50), records the exact call and moves the task to
waiting_approval without blocking anything — the sweep moves on to the next pod in the same
pass. approvalMode resolves per caller when a pod hasn't set one explicitly: serve
--dispatch's sweep and a non-interactive docket pod <p> dispatch both resolve to park; an
interactive foreground dispatch (a real TTY) resolves to wait. A pod's own stored
approvalMode (docket pod <p> config set approvalMode wait|park|refuse) always wins over the
caller's default. A parked approval is granted or denied exactly like any other (CLI, HTTP, MCP,
Telegram); granting it re-runs the same hop, carrying a single-use pre-grant matched by a stable
argument digest so the model's identical next call passes once without asking again. Left
untouched past the pod's approvalExpiryHours (docket pod <p> config set approvalExpiryHours
N, default 24), it expires and denies — the same fail-closed sweep a pre-hop approval gate's
pending approval already used.
A pipeline can also pause a task to ask a real question, not a permission: an input step
(- ask: {input: {from: <step-id>}}) mints a question from another step's output and moves the
task to waiting_input, distinct from waiting_approval in the CLI/HTTP/MCP surfaces even
though both read the same INPUT_REQUIRED A2A state. The intake recipe (§3.10) wires this to a
Lead's own typed brief: the Lead writes an objective/acceptance/resources/questions
brief and ends with READY/NEEDS-INPUT/REJECT; READY runs a deterministic check that every
declared resource (secret:NAME, path:P, or verify) actually exists before handing off to
the Implementer, NEEDS-INPUT asks the brief's own questions[] and returns to the Lead once
they're answered, REJECT fails the task outright naming the reason. An unanswered question past
its own deadline (docket pod <p> config set inputExpiryHours N, default 72 — a separate knob
from approvalExpiryHours, since a question is reasonable to leave open longer than a
permission) moves the task to blocked (blockedReason: "input_expired"), never failed.
# pipeline.yaml — a generic input step
steps:
- id: lead
role: lead
- id: ask
input:
from: lead
on:
answered: {goto: lead, max: 3}
declined: {goto: lead, max: 3}
- build: implementer
Finding out. Nothing above pushes a notification by itself. docket inbox [--json] [--since
<iso>] [--peek] (also GET /inbox, the MCP inbox tool, and Telegram's /status) is read-only
and computed live: every pod is enumerated, each task sorted into needsYou (any waiting_*
status, plus blocked), failed, doneSince or running, and a pending approval added to
needsYou unless its own task already carries it. A plain docket inbox call advances a durable
cursor so the next one's doneSince only shows tasks that finished meanwhile; --peek and an
explicit --since don't.
Pushing. A destination is a kind: channel YAML document, the same shape as kind: exporter
(§3.14). Seven dialects ship, all disabled except console (your own terminal, already the
inbox): desktop, webhook, command, ntfy, email and telegram notify only; console and
telegram may also decide (act on an approval from inside the channel). Console sends
nothing, so with nothing else enabled a parked task waits unseen until docket inbox: docket
doctor counts that as an issue once a pod exists (checks.notifications in --json), and
docket init, docket serve --dispatch and a foreground dispatch that found events print the
same warning; docket channels enable desktop is the zero-configuration fix. A channel declares
content: minimal|actions|conversation (default minimal) the same way an exporter declares
privacy, and widening it is the same confirmed, audited command shape:
docket channels enable webhook --set url=https://example.com/hook --set secret=WEBHOOK_SECRET
docket channels content webhook actions --yes
docket channels test webhook # one synthetic event, to check the URL/binary/topic works
docket notify flush [--dry-run] # push what's pending now; serve's sweep and dispatch already do this
webhook signs its POST per Standard Webhooks (webhook-signature: v1,<hmac-sha256>); command
runs a local binary with the event as JSON on stdin; ntfy/desktop/email/telegram each wrap
one more stdlib-only transport. Unlike exporters: (§3.14), a channel is a global catalog
entry, not something a pod.yaml names or scopes — every enabled channel watches every pod's
inbox.
Answering. A parked approval: docket approve <token> / docket deny <token>. A parked
question: docket chat <task-id> [--pod <project>] (interactive — shows the brief and any prior
answers, prompts once per schema property on a TTY, then answers) or non-interactively docket
pod <p> answer <task-id> [text] [--field name=value]... [--decline] — a bare text fills a
single-property question, --field names each property of a richer one. Both, plus POST
/tasks/<id>/answer and the MCP task_answer tool, resolve through the same
core.answers.answer_task function, so an answer is screened by the same input policy hook
regardless of which surface sent it.
Seeing it coming. docket pod <p> explain interruptions [--json] forecasts, from the pod's
own configuration alone (no live dispatch), every policy, pipeline gate and role rule that could
pause its next task, plus the resolved approvalMode and which notification channels are
enabled; docket pod <p> delegate prints one summary line from the same forecast after queuing
("Nothing in this pod will ask you." or "May ask you: 2 policy, 1 pipeline_gate — see: ..."). A
command you already expect can be pre-approved before it ever runs:
docket pod <p> pregrant <task-id> "<command>" [--tool bash] — matched by the identical digest
the live parked-approval matcher uses (whitespace-collapsed, otherwise exact), so a rephrased
command still asks, by design.
4. File reference
Hand-editing. Docket writes its JSON atomically: a file lock, a .bak of the previous
version, and a 0600 replace. If a file is later unreadable, docket restores it from .bak and
keeps the bad copy as .corrupt. Your editor does not take that lock, so hand-edit only while no
docket process (dispatch, serve) is running. For files marked no, use the command instead.
Global (~/.docket/)
| File | Format and key fields | Written by | Read on the live path by | Hand-edit |
|---|---|---|---|---|
fleet.json |
agents[{id}], bindings[{agentId,channel,peerKind,peerId}], security{isolationMode,networkMode} |
init, wire, gates |
isolation and network mode (isolationMode, networkMode), Telegram auth (bindings) |
careful. Use commands where they exist. |
docket-providers.json |
providers{<name>: kind: provider document} (fields in "Provider catalog" above) |
models provider add/remove |
endpoint resolution (baseUrl, dialect, auth, models[].id/contextWindow/maxTokens) |
via models provider add/remove/export. Malformed entries are named by docket doctor. |
docket-models.json |
default, roles{role: provider/model}, rankAnchors{economy,standard,premium} |
models set/preset/reset |
policy resolution for agents following policy; economy/standard back modelClass cheap/strong |
yes, but prefer models set. Malformed entries are ignored silently. |
docket-roles.json |
{"roles": {name: archetype}} (fields in §3.4) |
roles add |
tool narrowing, hop budget, gate contract; templates at provisioning | via roles add |
policies/*.yaml\|json |
one policy per file (§3.6) | policies init, init, you |
every tool call, task enqueue and hop output | yes, this is the intended interface |
docket-mcp-servers.json |
servers[{name,command,args,env,timeout,kind,tools,isolate}] |
mcp servers add/remove |
every turn | via command |
docket-exporters.json |
exporters{<name>: kind: exporter override} — only the keys you changed (enabled, endpoint, privacy/share, contentMaxChars, events) over the built-in |
exporters enable/disable/privacy/add/remove |
the export pipeline at the start of every turn: which destinations run, and at what level (§3.14) | via command. A hand edit that widens privacy skips the confirmation and the exporter.privacy audit entry. |
exporters-health.json |
{<name>: {exported,dropped,failed,…}} |
the export pipeline, after every turn | exporters show, doctor |
no |
docket-channels.json |
channels{<name>: kind: channel override} — only the keys you changed (enabled, capabilities, on, content, actors, config, secret) over the built-in |
channels enable/disable/content/add/remove |
docket notify flush, serve's sweep and a foreground dispatch, each after their own work: which channels run, and how much they carry (§3.15) |
via command. A hand edit that widens content skips the confirmation and audit entry. |
channels-health.json |
{<name>: {delivered,failed,lastOk,lastError,…}} |
core.notify.flush, after every delivery attempt |
nothing yet — no CLI surface reads it back | no |
notify-state.json |
{<dedupe-key>: version} plus an expiring list |
core.notify.flush, saved before delivering |
core.notify.diff_events on the next flush, to avoid re-sending an unchanged item |
no |
inbox-cursor.json |
{"next": "<iso timestamp>"} |
a plain docket inbox call |
the next plain docket inbox call's doneSince filter |
no |
docket-schedules.json |
schedules{pod: spec}, lastRun{pod: epoch} |
pod config set/unset schedule, serve (lastRun) |
serve --dispatch sweep |
via command; docket doctor names a bad hand edit |
secrets.json / secrets.meta.json |
{NAME: value} / {NAME:{added_at,rotated_at}} |
keys add/rotate/remove |
endpoint key lookup (after env) | no |
port-allocations.json |
allocations{pod: base}, 100 ports each from 3000 |
pod create/delete | implementer env DOCKET_PORT_BASE |
no |
docket-runs.json |
runs[{id,source,project,state,taskIds,…}] |
every dispatch | docket runs, /runs |
no (never pruned) |
docket-conversations.json |
conversations[{id,agentId,peerId,topic,status,…}] |
Telegram, conversations set |
Telegram channel | no |
sessions/<key>/session.json |
messages[], usage{inputTokens,outputTokens,turns} |
every turn | every turn (history, compaction) | no. maintain sessions reports sizes. |
traces/<pod>/<session>.jsonl |
one event per line {ts,session_id,agent_role,event_type,payload} |
every turn | docket trace, metrics, /traces; each record also reaches the enabled exporters as it is written |
no. trace expire prunes after TRACE_RETENTION_DAYS. |
approvals/<id>.json |
{token,project,role,action,state,created,context} |
gated calls | the approval wait | no. Answer with approve/deny. |
consult-parked/<q-id>.json |
one operator-v1.1 QuestionV11 |
a pod hop's consult |
dispatch, once, when it parks the task | no. Dispatch removes it; the task keeps the question. |
audit.log (+ .1) |
JSONL {seq,ts,user,pid,action,detail,prev_hash} |
every mutating command | docket audit, audit verify |
never. It breaks the hash chain. |
Built-in provider documents ship in the wheel at templates/providers/NN-<name>.yaml
(anthropic, openai, google, openrouter, ai-gateway, groq, mistral, deepseek,
xai, cerebras, together, ollama, lmstudio, local), not under ~/.docket/. The
catalog merges them with docket-providers.json, nearest-wins by name — a global write under a
built-in's name overrides that document but inherits its presets and pricing unless set
explicitly.
Built-in exporter documents follow the same pattern at templates/exporters/NN-<name>.yaml
(otel-collector, jaeger, langfuse, honeycomb, phoenix), every one enabled: false at
privacy: minimal. docket-exporters.json stores only what you changed on top of one.
Built-in channel documents follow the same pattern at templates/channels/NN-<name>.yaml
(console, desktop, webhook, command, ntfy, email, telegram); only console ships
enabled: true, and every one carries content: minimal. docket-channels.json stores only
what you changed on top of one.
Per agent (~/.docket/workspaces/projects/<pod>-<role>/)
.docket-meta.json, with each key and what uses it:
| Key | Used for | Set by |
|---|---|---|
model, modelSource |
the model this agent calls; whether policy changes follow it | models, profile |
role, pod, blueprint |
tool narrowing, gate, pipeline choice (Lead) | provisioning |
codebase, workDir |
the directories tools may touch; verify cwd (a dispatched task uses its own worktree) | provisioning |
verifyCmd |
the mechanical gate after this member's hop | pod set-verify, --verify |
budgetUsd, paused, pausedReason |
pod budget and auto-pause, Lead only | profile --budget, --resume |
maxReworkCycles, turnTimeoutS, verifyTimeoutS |
pod dispatch, Lead only | pod config set (§3.3) |
approvalMode, approvalExpiryHours |
unattended posture for a gated call (wait/park/refuse); how long a parked approval stays open before it expires and denies, Lead only |
pod config set approvalMode/approvalExpiryHours (§3.15) |
inputExpiryHours |
how long a parked question (waiting_input) stays open before it expires to blocked, Lead only — a separate knob from approvalExpiryHours, default 72 |
pod config set inputExpiryHours (§3.15) |
portRangeStart, portRangeCount, scratchDir |
Implementer environment DOCKET_PORT_BASE/COUNT, DOCKET_SCRATCH_DIR |
provisioning |
persona |
the persona block in the system prompt | persona set/clear |
sessionKey, projectKey |
shown by docket scope; dispatch builds its own per-task session key |
scope |
templateVersion, kind, scope, stack, name, description, created |
informational. stack and name fill templates at provisioning |
provisioning |
The Markdown files are covered in §2 (what reaches the
model) and §3.2 (what to edit, and what overwrites it). Only
the Lead has TASK_LIST.json, the pod queue. Change it with docket pod <p> delegate and
queue --retry, never by hand while a dispatch holds a claim.
Org specialists (~/.docket/workspaces/{manager,knowledge,security}/)
These have the same files, minus TOOLS.md, tasks/ and the pod keys. They are shared by
every project. Pod dispatch never uses them. Customize them the same way (§3.2).
5. Sharp edges
These are true of the current code. Each one is a reason to check a setting's effect instead of assuming it. Phase 26 (ADR 0008, closed 2026-09-26) fixed the rest of the original list; what remains below is the honest boundary, not a backlog.
WORKFLOW_AUTO.mdandmemory/are not in the prompt (§2). EditSOUL.md/MEMORY.md.- Your prompt text belongs in
INSTRUCTIONS.md. It is operator-owned (docket never writes it), composes right afterSOUL.md, and survivesset-verifyandpod sync; generated files are re-rendered wholesale bydocket pod <p> syncwhen a template or archetype changes (--dry-runshows the diff, doctor flags stale members). - A skipped file is silent on the live path, but doctor names it. An invalid schedule spec,
model-policy entry or overlay role — global or pod-scoped — never crashes a fleet — the loader
skips it — and
docket doctorreports each one with pod (when applicable), file, key and reason (a broken policy file instead fails closed at evaluation, §3.6). Run doctor after hand-editing any registry. - A live
warn/redactpolicy hit is recorded in the audit log (docket audit, actiontool.warn), not in traces — sodocket trace/metricswon't show it. - A running
docket servekeeps the exporters it started with. Export pipelines start once per process (§3.14), sodocket exporters enable,disableandprivacyreach a long-runningserve --dispatchonly after it restarts, and that includes narrowing: until the restart, it keeps sending at the old level. Restart it after any change to what leaves. - A destination gets only what was captured while it was allowed to. Prompts, replies and
tool output are recorded only while an enabled exporter grants them (§3.14), so a wider level
cannot send an earlier session's conversation, and
preview --level conversationon that session says so. docket deletekeeps an unmerged branch. Teardown deletesdocket/<pod>/<member>when it is merged into your current branch; an unmerged one is kept and the command to remove it is printed.