Security: Layered & Convention-Based
Philosophy: Security comes from layered defaults — an always-on tool-call gate, agent instructions, an optional read-only reviewer role, and human git review — so that the common cases are covered without extra commands, and nothing about a run leaves the host until you choose what may.
Status / honesty note. docket runs the agent turn itself (
core/agent_loop.py), and every tool call an agent makes passes through one chokepoint (core/tools.py'sdispatch_tool) before it executes — there is no external daemon in the loop any more, and nothing to bypass it. That chokepoint is always active: an argument-aware command classifier plus thepre_tool_callpolicy hook decideallow/ask/denyfor every call; no flag or command turns it off. A dangerous operation not on the curated allowlist (rm,dd,docker,systemctl, an unlisted shell interpreter, ...) is routed to docket's own approval store and blocks the call until a human answers — the same store a pod-dispatch hop held on arequireApprovalRoles/pipelineapprovalstep, or a task a guardrail policy flagged at enqueue, also uses (see "Guardrail Policies" below).git/npmstay on the curated allowlist for usability, so a plaingit pushisn't gated by itself — see "High-Risk Actions" below for the argument-aware exception.There is exactly one approval system, and it is answerable from four places — all audit-logged, tagged with the channel that answered: a CLI channel (
docket approve/docket deny), a headless HTTP endpoint (docket serve'sPOST /approvals/<token>), MCP, and Telegram (docket's own bot, wired withdocket wire— a decision there lands in the same audit chain as a CLI one, taggedchannel="telegram"). The headless channels mean CI jobs and automation can vote without a chat account. Approvals fail closed on timeout — an in-turn "ask" that actually blocks a live tool call (an interactive foreground dispatch, which resolves toapprovalMode: wait) denies itself after 120 seconds with nobody watching; a pre-hopapprovalgate (the async, pre-dispatch-level kind) denies after 15 minutes. An unattended pod never blocks on that 120-second wait at all —serve --dispatch's sweep and a non-interactivedispatchboth resolve an unset pod toapprovalMode: park(Phase 34, D-50): the in-turnaskis recorded and the task is parkedwaiting_approvalimmediately, with no live wait and no risk of one stuck hop stalling every other pod in the same sweep. A parked approval is answered exactly the same way (any of the four channels above), re-runs the same hop on a grant rather than skipping ahead, and — left untouched — expires after the pod'sapprovalExpiryHours(24h by default) and denies, the identical fail-closed sweep a pre-hop gate's pending approval already used. See "The operator loop" below for how a human actually learns a task is waiting.An "ask" verdict always blocks the call and always sits in docket's own approval store, answerable identically by the CLI, HTTP, MCP, and Telegram channels. The Telegram bot itself is inbound-only and never messages a chat first (telegram-integration.spec.md's Command-grammar requirements 7-8). Notifications exist since Phase 34, but only through an opt-in
kind: channelyou enable yourself; every channel ships off except your own console, which sends nothing (see "The operator loop" below).A gated call's approval now carries a
rationale(the model's own preceding sentence, screened and truncated, so a claim to weigh and not a verified fact) and the optionsapprove_once,approve_task(the identical call for the rest of the task, only for the role that asked) anddeny;--reasonon approve/deny is screened and audited with the answering channel. bwrap/Docker workspace isolation is a separate layer on top, opt-in (docket gates isolate on; it needs bubblewrap on Linux or a running Docker) and consulted by the turn loop: when it's on, every real dispatch hop runs sandboxed, and if neither backend is usable the turn refuses to run rather than falling back unsandboxed (an auditedisolation.refusedentry — no LLM call, no tool executes).docket gates statusreports which state applies. Requirements and coverage: "Workspace isolation (opt-in)" below, andspecs/functional/security-gates.spec.md.
How Security Works (Layered)
1. Agents Are Instructed Not to Do Dangerous Things
A pod member's SOUL.md/AGENTS.md carry short safety lines (the Implementer's, verbatim):
- Never push to main/master without HITL approval; never delete files without explicit instruction.
and every member's AGENTS.md ## Red Lines repeats "Never push to main/master or delete files
without HITL approval" plus the stay-in-this-pod rule. Nothing instructs an agent not to commit.
These are prompt-level constraints: agents are instructed to follow them. On top of that,
docket's own tool-call chokepoint is always active regardless of the prompt: non-allowlisted
dangerous operations (rm, dd, docker, systemctl, ...) require approval before they run —
see the status note above for who can answer, and for the git/npm carve-out.
2. A Reviewer Can Veto (when the pod has one)
The default pod from docket init is lean — Lead + Implementer, no Reviewer. Add one with
docket init --pod full, --with reviewer, or later docket add reviewer. When present:
- Its role prompt tells it to review diffs "for correctness, security, and requirement fit". There is no fixed checklist — what it catches is the model's judgment, not a scanner.
- It is structurally read-only: its role's
denied_toolsremovewrite/edit/bashfrom its tool registry, so it cannot modify code rather than being told not to. - Its reply must carry one
APPROVEorREQUEST-CHANGESmarker line.REQUEST-CHANGESsends the task back to the Implementer for one bounded rework cycle (default), then fails it; a missing or ambiguous marker blocks the pipeline like a rejection.
What Engineers Do
Before Starting Work
Nothing. Security is built-in.
During Agent Work
Nothing. The tool-call gate runs on every call; a Reviewer, if the pod has one, reviews
automatically. Answer any pending approvals (docket approve).
Before Committing
# 1. Review the diff
git diff
# 2. If looks good, commit
git commit -m "Feature: description"
# That's it.
Optional: Manual Scan (if suspicious)
# Only if you suspect injection, run:
grep -rn "ignore previous" ~/Sites/myproject/src/
# That's it. No complex tools needed.
How Each Layer Works
Layer 1: Prevention (Agent SOUL.md)
- Agents have constraints written into their identity prompt
- Instructed not to push to main/master or delete files without approval (prompt-level, not enforced by the prompt itself — the tool-call gate is what enforces)
- No code — just instructions
Layer 2: Detection (Reviewer verdict, optional role)
- Runs on every dispatched task in a pod that has a Reviewer
REQUEST-CHANGEStriggers one rework cycle, then fails the task- Model judgment, not a scanner — keep reviewing diffs yourself
Layer 3: Engineer Review (Git Diff)
- Engineer reviews diff before commit
- Final human check
- Simple git diff, that's it
Layer 4: Guardrail Policies (Automatic, on real dispatch tasks)
- A small set of installed policies (
docket policies) scan text at two points in docket's own pod-dispatch pipeline — not a raw Telegram chat, only work that goes throughdocket pod <p> delegate/dispatch: - Once, when a task is delegated — before it's even added to the queue.
- On every hop's real reply, as the pipeline runs.
- A match can
allow/warn(just logged),redact(scrub it before it's stored),block(reject the task, or stop the pipeline where it tripped), or — enqueue-time only —require_approval(routes into the approval store above). docket policies listto see what's installed,docket policies test <hook> <role> "<text>"to dry-run one without touching anything real. Add--tool <name>when testingpre_tool_callagainst something other thanbash(the default), so a non-shell tool isn't misclassified against the command allowlist.- A broken policy file fails closed. Unparseable JSON, a pattern that doesn't compile as a
regex, or an unknown action makes that file evaluate as
blockwithin its readable scope — the hook and roles it declares, or every hook and role if the JSON itself won't parse — named to the file so you know what to fix.docket doctorcatches this before a live turn does.
Layer 5: High-Risk Action Classes (Automatic, and — since Phase 19 — argument-aware)
- A small, built-in list of especially consequential command patterns: money-movement,
prod-deploy, secret-access (
docket gates classesprints all of them). - Wired onto every
bashcall docket dispatches, not just a pod'sverifyCmd. Since docket runs the turn loop itself,core/tools.py'sdispatch_toolclassifies the whole command line — including every segment behind a;/&&/||/pipe — before a call is allowed to run.git statusis allowed;git push origin productionasks, because the classifier reads the arguments, not just the binary name. A pod'sverifyCmdstill refuses outright on a match (fails closed, before the shell even starts) since it runs synchronously with no approver reachable mid-hop; a hop's real output is separately scanned for a match on the way through the pipeline (flagged, not blocked, by itself). - What this does NOT do by default: lock down network egress. With the default
network open,bashcan still reach the network through interpreters and package managers on the curated allowlist (python3,node,git clone, ...) — thefetchtool is domain-allowlisted and the inspectable path, but not the only one until you rundocket gates network none, which cuts the jail's network (verify commands andrun:steps still run on the host). It is also scoped to what docket itself dispatches: a process started outside docket's turn loop is outside this gate entirely. - Only
bashis jailed, and only with isolation on. The command gate above applies to everybashcall; the opt-in bwrap/Docker isolation (next section) jailsbashand stdio MCP servers. The other built-in tools are not jailed:fetchis domain-allowlisted, andwrite/edit/read/glob/grepare bounded by role denials, policy and path confinement, not by a sandbox. - A pod can widen its own allowlist with
docket pod <p> config set allowCommands pytest,uv(comma-separated) for its own turns only — a high-risk-class binary likegitornpmis refused at write time, and an allowlisted-by-pod binary is still redirect-sensitive, sopytest > /etc/passwdstill asks.approvalModeis how a pod chooses what an unattendedaskdoes: unset, it resolves per caller —parkunderserve --dispatch's sweep or a non-interactivedispatch,waitunder an interactive TTY. An explicitwaitblocks the call for the usual 120-second in-turn timeout regardless of caller;parkrecords the call and parks the task instead of blocking (see "The operator loop" below);refusefails the call fast withapproval_unavailable, the one posture that never gives a human a chance to grant it later.
Workspace isolation (opt-in): the sandbox for the agents' shell
Off by default. Without it, an agent's bash runs on your machine as you, bounded by the
tool-call gate and the policies above but not by a sandbox. Turn it on when you want the shell
contained as well as gated:
docket gates isolate on # needs a backend (below); exits 1 naming the fix if there is none
docket doctor # names the backend a turn will use
docket gates isolate off # back to the host; both commands are audited (gates.isolate)
What a host needs to turn it on. One sandbox backend. docket probes bwrap first, then docker:
| Host | Backend | How to get it |
|---|---|---|
| Linux | bubblewrap (bwrap), preferred: no daemon, and the jail sees the host's toolchain read-only |
apt install bubblewrap, dnf install bubblewrap, pacman -S bubblewrap |
| Linux or macOS | Docker, with the daemon running | Docker Desktop, Colima or OrbStack on macOS (bwrap does not exist there) |
Under Docker the jail is only as capable as its image, DOCKET_SANDBOX_IMAGE (default
alpine:3.20): a jailed git commit needs git in the image, and Python work needs python3.
docket doctor checks the image for git and warns with the fix. DOCKET_SANDBOX_BACKEND=bwrap|docker
forces one backend. Nothing here is needed while isolation is off.
What it covers, once on.
- Every bash call runs in the jail. Only the agent's workspace and the task's worktree are
writable; the rest of the host is read-only or absent. The task worktree's git directories are
writable, so the agent can commit, while the repository's hooks, config and attributes stay
read-only, so nothing the jail writes runs later in your own unjailed git.
- Stdio MCP servers start in the same jail, unless you declared one --no-isolate (audited and
listed by docket doctor).
- A jailed process sees only PATH, the pod's injected variables and your git identity, never
docket's credentials.
- It fails closed. If isolation is on and neither backend is usable when a turn starts, the
turn is refused before any model call and audited as isolation.refused; it never falls back to
running unsandboxed.
- docket gates network none (or a pod's network: none) cuts the jail's network. It needs
isolation on: with isolation off, such a turn is refused, because only the jail can enforce it.
What it does not cover. read, write, edit, glob and grep run inside docket and are
confined to the workspace and codebase by path, not by the jail (symlinks out of those roots are
refused either way). fetch runs inside docket under its domain allowlist. A pod's verifyCmd
and pipeline run: steps are your own commands and run on the host, with docket's credentials
stripped from their environment.
Layer 6: Telemetry export (what leaves the host)
- Off by default. Every built-in exporter (
docket exporters list) shipsenabled: false. Nothing is sent anywhere until an operator runsdocket exporters enable <name>, which resolves a credential (prompted, never a CLI argument), probes the real endpoint, and only then writes the minimal override that turns it on. - Structure only, unless you choose more. Each exporter declares a privacy level:
minimal(the default for every built-in) sends model and tool names, timing, measured token counts, pass/fail and ids, and nothing a person wrote or read.actionsadds tool arguments and error text;conversationadds prompts, replies and tool results;fulladds the system prompt.share: [...]names the classes exactly.docket exporters show <name>lists what leaves ("Leaves this host"), anddocket exporters preview <name>shows the exact spans a real local session would send, without sending them. - An allowlist, not a filter. A span attribute leaves only when its class is granted, so a
trace field nobody has classified stays home. A conversation is filtered part by part:
sharing
promptsdoes not carry a tool result inside it. Credentials and secret-shaped values are redacted before anything is written, at every level. - Captured only when asked for. Prompts, replies and tool output enter the local trace only
while an enabled exporter grants them; with every exporter at
minimal, the local trace holds no more than it did before exporters existed. - Widening is deliberate and recorded.
docket exporters privacy <name> <level>(orenable --privacy) lists each newly shared class and the destination host and asks; off a TTY it refuses without--yes. Narrowing never asks. Every change is anexporter.privacyaudit entry (from,to,host). Each exported session also carriesdocket.privacy, so the destination shows what it was allowed to receive. - A running
docket servekeeps the level it started with. Export starts once per process, so a change — narrowing included — reaches a long-runningserve --dispatchonly after it restarts. A one-shotdispatchorharness runpicks it up at once.DOCKET_NO_EXPORT=1turns export off for one process. - No new dependency, no vendor SDK. The wire format is hand-rolled OTLP/HTTP JSON over the
stdlib (
edges/adapters/exporters/otlp_http.py) — D-24's cut of the OpenTelemetry SDK stands (D-48), and export stays a zero-dependency projection of docket's own trace events, never a second source of truth. - Never blocks a turn. The export pipeline is a bounded queue drained by a background
thread — a slow or unreachable destination drops spans past the bound and records it in that
exporter's health counters (
docket exporters show <name>), it never raises into the agent loop. - A pod only documents intent, never activates.
pod.yaml'sexporters:list is validated against the live catalog and reported byconfig explain, but naming a destination there does not turn it on —docket exporters enableis still the one command that flipsenabled: true.
The operator loop: how you find out, and how you answer (Phase 34, D-50)
- A parked task is not a silent one.
docket inbox(alsoGET /inbox, the MCPinboxtool, and Telegram's/status) is a live, read-only view — every pod's tasks and pending approvals sorted into needs-you, failed, done-since-last-look and running — computed fresh each call, not a separate store to fall out of sync with the truth. It's the one place that answers "does anything need me right now," across every pod, without opening each one. - Off by default, same as export. A push notification is a separate, opt-in
kind: channeldocument (docket channels): seven dialects ship (console,desktop,webhook,command,ntfy,email,telegram), and onlyconsole— your own terminal, already the inbox — ships enabled. Enabled is not the same as reaching you: console sends nothing, sodocket doctorflags a home with pods and nothing else on, andinit/serve --dispatchwarn too; the fix is one command, never automatic. Nothing leaves this host to notify you of anything until you rundocket channels enable <name>. Each dialect has a closed maximum of what it may do: every dialect cannotify; onlyconsoleandtelegrammay everdecide(act on an approval from inside the channel itself); a document that tries to exceed its dialect's maximum is refused at parse time, not silently ignored. - A notification carries as little as an exporter does, by the same default.
content: minimal(default) names what changed, nothing more;actionsadds an approval's rendered command;conversationadds a task's question or brief. Widening is the same confirmed, audited command shape asdocket exporters privacy:docket channels content <name> <level>lists what starts showing up and asks, refusing off a TTY without--yes; narrowing never asks. - Telegram's push is not the inbound bot talking to itself.
core/telegram.py's bot is still exactly what "It isn't a chat" above describes: inbound-only, five verbs now (/approve,/deny,/status,/delegate, and/answer <task-id> <text>for a parked question), and it never sends anything it wasn't asked to. Thetelegramchannel (docket channels enable telegram --set actors=<chat-id>) is a second, independent mechanism: it can push a notification to a chat id you explicitly listed, and only that chat id — never everyfleet.jsonbinding, never triggered from inside the bot's own poll loop. - Answering doesn't require re-running anything by hand. A parked approval is answered like
any other (
docket approve/docket deny, HTTP, MCP or Telegram) and re-runs the exact hop it parked in, carrying a single-use pre-grant so the model's identical next call passes without asking again. A parked question (waiting_input, from a pipelineinputstep or a Lead's own intake brief) is answered withdocket chat <task-id>(interactive, prompts once per field) or non-interactively withdocket pod <p> answer <task-id> [text] [--field k=v]... [--decline]— both call the sameanswer_taskfunction HTTP and MCP use, so an answer is screened through the same input policy as any other text reaching an agent. - You can see what would ask before you delegate anything.
docket pod <p> explain interruptionsforecasts, from the pod's own configuration alone (no live dispatch), every policy, pipeline gate and role rule that could pause its next task, plus which notification channels are enabled to tell you —docket pod <p> delegateprints one summary line from the same forecast after queuing.docket pod <p> pregrant <task-id> "<command>"grants one exact command ahead of time, matched by the identical digest a live parkedaskwould use, so a command you already expect and approve of never has to park at all.
Testing Security (Simple)
Test 1: Does the Implementer Carry Its Safety Lines?
# Check the implementer's constraints (replace "myapp" with your project name)
grep "Never push" ~/.docket/workspaces/projects/myapp-implementer/SOUL.md
# Should find: "Never push to main/master without HITL approval; ..."
Test 2: Is the Reviewer Read-Only?
# Only if the pod has a Reviewer (replace "myapp" with your project name)
grep "Read-only" ~/.docket/workspaces/projects/myapp-reviewer/SOUL.md
docket roles show reviewer # its denied_tools are what actually enforce it
Test 3: Review Agent Commits
cd ~/Sites/myproject
git log --since="30 days ago" --format="%an %s" # review automated/agent commit authors
git commit is on the curated allowlist and no prompt forbids it, so an Implementer can commit
locally. Review what landed before you push.
The gate itself is covered by docket's own test suite; these checks confirm your pod's setup.
What If Something Goes Wrong?
Prompt Injection Found
# Reviewer will catch it and REJECT
# If somehow missed, search manually:
grep -rn "ignore previous\|you are now" ~/Sites/myproject/src/
Agent Tries to Commit
Nothing stops a local git commit: git stays on the gate's curated allowlist (it's used
constantly for benign work), and no prompt forbids committing. A plain git push is also allowed;
git push ... main|master|production|prod matches the prod-deploy high-risk class and asks.
The prompt-level "never push to main/master" line, a Reviewer if present, and your git-diff review
are the backstops for the rest.
Truly destructive bins (rm, dd, docker, systemctl, ...) are gated on a default install
(see the status note above).
Hardcoded Secret Found
# Reviewer will catch it and REJECT
# If missed, search manually:
grep -rn "api_key.*=.*['\"][a-zA-Z0-9]{20,}" ~/Sites/myproject/src/
The Audit Log (docket audit)
Every gate flip, approval grant/deny, key/model/profile/pod change, and every exporter added,
removed, enabled, disabled or given a new privacy level, writes one line to
~/.docket/audit.log — who, what, when. Secret values are never written, only names (a
key's NAME, a model id, an agent id).
docket audit # last 20 changes
docket audit 50 # last 50
docket audit verify # walk the tamper-evidence chain
The log is hash-chained: each line records a hash of the one before it, so docket audit verify
can tell you the exact line where something stopped matching — i.e., where a line was edited or
removed after the fact. There's no environment switch to turn recording off. The log rotates to a
single audit.log.1 backup; the new file's first line claims its predecessor, so verify
reports a break if that backup is missing or altered. Only one generation back is checkable, and
deleting audit.log and audit.log.1 together looks like a fresh install — erasure is made
evident, not prevented.
What it can't see. The log only records what docket does. Since docket now owns the
Telegram bot itself, a bound chat's /approve, /deny, /status, and /delegate all go through
docket and land in this log, tagged channel="telegram", the same as a CLI or HTTP decision. What
it genuinely can't see: a human editing docket's own JSON files (fleet.json, .docket-meta.json,
...) directly with a text editor instead of a docket command, or any process a user starts entirely
outside docket's turn loop — docket gates the tool calls it dispatches, not every process on
the host. That's a structural boundary of what docket can observe, not a gap a future version
quietly closes.
Summary
Security = 3 things you see, on top of the always-on tool-call gate:
- Agent constraints (in SOUL.md) → Discourages dangerous actions (prompt-level)
- Reviewer verdict (optional pod role, read-only) → Can send work back or fail it
- Engineer review (git diff) → Final human check
Hard enforcement (the tool-call gate) is unconditionally on — no flag or command disables it. Workspace isolation (bwrap, else Docker) is opt-in with docket gates isolate on, which needs one of those backends on the host, and docket gates network none is the opt-in network lockdown. On top of all three, two automatic layers run with no engineer action at all — guardrail policies and the high-risk action classes (above) — and every gate/approval change either layer makes lands in the tamper-evident audit log. What leaves the host is governed the same way (Layer 6): every exporter ships off and at minimal, and sharing more is a confirmed, audited command. An unattended pod's "ask" now parks instead of blocking a sweep, and how you find out is the same shape again ("The operator loop" above): every notification channel ships off except your own console, which sends nothing, so docket doctor warns until you enable one that delivers, and widening what one shares is a confirmed, audited command too.
Inspecting the Automatic Layers
None of this needs a human to run day to day — it's here for when you want to check it yourself:
docket gates status # gate always active; isolation mode
docket gates classes # the high-risk action classes, and exactly what's wired vs. not
docket policies list # installed guardrail policies
docket doctor # catches a broken policy file before a live turn does, and more
docket approve # list pending approvals in docket's own store
docket audit verify # walk the hash chain -- surfaces an edited/removed line, doesn't prove none happened
docket exporters list # every trace destination: on or off, and what it SHARES
docket exporters preview <name> # the exact spans it would receive, without sending them
docket inbox # everything across every pod that needs you, right now
docket channels list # every notification destination: on or off, and what it shares
docket pod <p> explain interruptions # what could pause this pod's next task, before you delegate it
Commands You Actually Use
# Initialize the current project once (Lead + Implementer)
docket init
# Check only this project's readiness and task state
docket status
# Queue and run work
docket pod myproject delegate "<task>"
docket pod myproject dispatch
# (a Reviewer, if you added one, reviews automatically)
# Review and commit
cd ~/Sites/myproject
git diff
git commit -m "Feature: ..."
That's the whole loop.
Key Insight: Good security is invisible. It just works.