derbent

Derbent is a tool-call guard gateway for coding agents. Its name comes from the guard posts set up at mountain passes in Turkish history: the guard decides who may pass and records every passer-by. Derbent does the same thing for coding agents' tool calls.

Purpose and positioning Its goal is to intercept and decide on tool calls before the agent executes them using a unified policy, and to leave tamper-evident logs; important calls that require attention wait for human confirmation. Officially, it is explicitly stated to be used to guard against mistakes and prompt injection, and to preserve audit trails, while also emphasizing that it is not a sandbox: an agent that can already run shell commands as you can bypass it (see the "Limitations" section).

Main capabilities

• Unified policy: every call that reaches Derbent (whether an MCP tool or a CLI built-in tool) is decided by the same set of rules, and rules can use the three actions allow, deny, and ask based on agent, tool, and parameters, with the first matching rule taking effect. The same set of rules applies to MCP tools and built-in tools (such as shell) across the four CLIs, and the repository can also add project rules that can only be stricter.
• Approvals: calls that a rule determines to be ask wait for you to approve with a keypress in the terminal UI, and are automatically denied after 50 seconds by default.
• Receipts: each call generates a hash-chained receipt; derbent verify will point out the first receipt at which the chain breaks after a receipt has been edited, moved, inserted, or deleted. Officially, it is advised to keep the head hash it prints so that the deletion of the latest receipt can be detected.
• Shared memory and handoff: agents can save notes per repository and can leave tasks for each other.
• Pin: when the tool definitions of a downstream server change, its tools can be "pinned" and not allowed through.
• Budgets: used to stop agents stuck in loops.

Integration method Claude Code, Codex, GitHub Copilot CLI, and Antigravity CLI connect to Derbent as the same MCP server, and your other MCP servers can be placed behind it. Each CLI's pre-tool hook sends its built-in tools (such as shell and file editing) through the same gate. Every call is decided by your rules and recorded.

Installation and initialization The binary and SHA256SU for the corresponding system can be downloaded from the latest releaseMS, after verifying the hash it is placed on PATH and named derbent (derbent.exe on Windows); it can also be built from source with Go 1.27 or later. There are also Homebrew (brew install tunahanaliozturk/tap/derbent) and Scoop installation methods. The official documentation states that every release can be rebuilt byte for byte from its tag. derbent init shows each change and asks once before making any changes; it first copies each file that will be modified, and it will not replace your existing entries; use --dry-run to only show the changes. It also adds the derbent gate hook to each CLI's settings. After that, start the agents as usual; their calls will appear in the UI, and calls whose rule decision is ask will wait here for you.

Rules and call decisions Rules are located in config.toml under the user configuration directory (%AppData%\derbent\ on Windows, ~/.config/derbent/ on Linux, ~/Library/Application Support/derbent/ on macOS). Tools of downstream MCP servers are named <server><tool>, and built-in tools of the CLI are named native<tool>. You can see how a call will be decided before it actually happens: the command prints each rule and the reason it matched or did not match, up to the first match, then prints the project's rules, budget, pin, and grant, and finally gives the conclusion for this round of calls under the above rules (for example, verdict: ask (rule:3)). Rules support glob, provide the three presets watch, balanced, and strict, and support project rules, budgets, and rule suggestions.

Receipt details Receipts retain parameters after secret masking, and for content returned by tools only retain its size and hash. The official documentation points out that anyone who can write to the database can still rewrite the entire chain or delete the latest receipt, so if you want to be able to distinguish this later, you should store the head hash elsewhere. Receipts and verify support exports that can be verified without depending on the database.

Performance (officially measured on GitHub-hosted runners on 2026-10-01) Linux (Intel Xeon Platinum 8370C)With 4 vCPUs each on Windows (AMD EPYC 9V74), median of ten runs (p50): on Linux this gate adds 499.5 µs to one MCP call, and on Windows 616.0 µs; the cost includes the extra stdio hop, rule decisions, project rule checks, and writing the receipt to SQLite. On Linux, a hook call is about 2.1 ms more than directly launching the binary; on Windows it is about 24 ms more, most of which is process startup. The official statement says these numbers come from a single run on a shared runner, and variation between runs can exceed the interval of a single run: the previous day, the same code on the same Windows CPU model measured this gate at 459.5 µs relative to a direct MCP call, whereas here it is 616.0 µs. The results page includes p99, calls per second, and caveats.

Support and Experimental Status The support for Codex and Antigravity CLI is experimental, configured according to their documentation, and has not been checked in a real session. Claude Code and Copilot CLI (1.0.88, 2026-10-02) have actually been checked.

Known Limitations and Risks (key items officially listed)

• Only calls that pass through this gate can be seen; tools that the CLI never hands to its hook (for example, Codex's managed web search) are out of scope.
• Argument glob matching matches strings rather than semantics: git push* does not match cd repo && git push .
• Approval is used to guard against mistakes and prompt injection inside MCP, but it cannot stop an agent that can already run shell commands as you: it can run derbent approve itself.
• Receipt export can only show that its last run was unchanged if you retained the header hash, and it can never prove that nothing was omitted.
• Recommendations reject the shells, launchers, and operators it knows about, but text rules can be fooled, and such lists cannot be exhaustive; allow on a command prefix will pass any option.
• The address for handoff is a label rather than an identity: any agent that can call handoff_take can claim all open handoffs sent to *.
• Approval depends on you being present to observe; when unattended, an ask is rejected after timeout.
• Pin trustthe definition it sees for the first time, including once updating tools newly added to a server that has already been pinned, so for servers whose updates you do not review, you should explicitly name the allowed tools.
• Calls in flight at the same moment may cross a budget together.
• CI runs tests on Windows and Linux, and only builds on macOS.
• The team audit trail (syncing receipts from each machine out and providing exports to a SIEM) is currently only an idea, not a plan.

There is corresponding documentation for installation, rules, approvals and UI, built-in tools, downstream servers and tool pinning, receipts and verify, memory and handoff, demos, design documents and decision notes, and so on; see changelog for the change log; see CONTRIBUTING.md for building, testing, and submitting changes; see SECURITY.md for reporting vulnerabilities. The project uses the Apache 2.0 license, see LICENSE.