keeperguard

The failure mode

An agent loop is not a program with one entry point. It crashes, gets retried, gets resumed from a checkpoint, gets run twice by an over-eager scheduler. All of that is survivable when the agent's actions are reads. It stops being survivable the moment the agent can move money.

The specific shape of the bug: an agent turn decides to send a payment, the HTTP call succeeds, the process dies before the response is recorded, the turn is retried, and the payment goes out twice. Nothing in the agent's own reasoning can prevent this — by the time the retry happens, the evidence that the first attempt succeeded is gone.

keeperguard closes that hole by making the request key a function of the decision rather than something generated at call time. Two turns that reached the same conclusion produce the same key, and the second one cannot broadcast.

The other failure mode: the agent edits its own cap

Everything above works as a library, and a library is a limit the agent's own code enforces. The agent that imports the guard is the agent that can stop importing it — one changed line, or one convincing instruction inside a document it was asked to read, and the cap is gone. That is a convention, not a guardrail.

KeeperHub already has an MCP server, and it is good — I connected to https://app.keeperhub.com/mcp (serverInfo: keeperhub 1.2.0) with this project's org key and listed 35 tools, execute_transfer and execute_contract_call among them. keeperguard is not an alternative to it and pitching it as one would be dishonest. What that surface does not carry is a ceiling: execute_transfer takes chain_id, to_address, amount, token_address, idempotency_key — amount is a free parameter, with no per-action cap, no daily cap and no destination allowlist in the schema the model is handed. And idempotency_key is optional and supplied by the caller: exactly the value a retried turn cannot reproduce, because the process that died was the one holding it. That stops a double-click, not a crash-loop.

So keeperguard runs as an MCP server of its own — the policy layer you put in front. The model gets four tools and nothing else:

There is no tool that raises a limit, and there is no tool that reaches the execute API directly. The model never sees the KeeperHub API key. Its spend cap is enforced in a different operating system process, from a policy loaded before the first token was generated. A prompt is a suggestion; a tool boundary is not.

It fails closed. Start it without KEEPERGUARD_MAX_PER_ACTION and KEEPERGUARD_MAX_PER_DAY and the process exits before it speaks a word of protocol — there is no permissive default to forget to override. A refusal comes back as a tool error the model can read and adapt to (policy_violation, carrying the problems and the policy itself), not as a dropped connection; a call to a tool that does not exist is a protocol error instead, because isError would tell the model to try again.

"mcpServers": {
  "keeperguard": {
    "command": "bun",
    "args": ["run", "/path/to/keeperguard/bin/mcp-server.ts"],
    "env": {
      "KEEPERHUB_API_KEY": "kh_…",
      "KEEPERGUARD_MAX_PER_ACTION": "0.01",
      "KEEPERGUARD_MAX_PER_DAY": "0.05",
      "KEEPERGUARD_ALLOWED_DESTINATIONS": "0x90EE…"
    }
  }
}

60 seconds of it running

Proof of execution — Base mainnet, real funds

Four executions, every one of them a real Base mainnet transaction, every receipt read at a public RPC rather than taken from KeeperHub's own status endpoint:

What happens between "the agent decided" and "the chain saw it"

1. Policy check, before any network call. Chain allowlist, destination allowlist, per-action value cap, and a rolling 24-hour cap computed from the agent's own settled history. A decision that violates a cap costs nothing and reveals nothing — no request is made.
2. Local replay short-circuit. If this exact decision already settled, the original result is returned without touching the network.
3. Simulation on the exact body about to be sent. Continue only on success && !wouldRevert — this catches bad addresses, insufficient balance and reverts before broadcast.
4. Broadcast under a derived Idempotency-Key: sha256 of the canonicalised decision, formatted as a UUID.
5. Poll to terminal state, honouring X-Poll-Interval-Hint, recording transactionHash and transactionLink.

Every phase appends to a hash-chained JSONL ledger, so an operator who was not watching can verify afterwards that nothing was inserted, edited or dropped: each record commits to sha256(prevHash + canonicalJSON(record)). The demo deliberately edits a record to show verification failing when it should.

Why the key is derived, not generated

idempotencyKey({ intent: "transfer", agent: "pico", chainId: 8453,
                 recipientAddress: "0x90EE…", amount: "0.00001",
                 reason: "keeperguard reference execution", epoch: "2026-07-27" })
// → 2425d7ef-9b69-8d20-83ad-6a27c6cd9d28, every time, from any process

Field order does not matter — the decision is canonicalised before hashing, so an agent that rebuilds the object differently still converges on the same key. Two fields are load-bearing: reason is part of the hash, because an agent that re-derives the same transfer for a genuinely different reason has made a new decision and should be allowed to spend again; epoch is the explicit "this is a new occurrence" marker — a date bucket, an invoice id, a block number. That is the knob that makes a recurring payment possible without making a repeated payment possible.

Two layers, verified separately

A guarantee that lives only in one JSONL file is one rm away from being no guarantee at all — so the demo goes around its own ledger and checks KeeperHub's server-side idempotency too. Both rows below were observed live, not read from docs.

Limitations

Stated because a guard whose edges you don't know is worse than no guard. The rolling daily cap is enforced against one ledger — two guards on separate ledger files do not see each other's spend; worse, the ledger append is a read-then-write, so two MCP servers pointed at the same file can interleave and break the chain. One ledger per server process is the only supported configuration, and a shared ledger needs a lock this does not have. Ledger integrity is tamper-evident, not tamper-proof: the chain proves an edit happened, it does not prevent one; anchoring the head hash onchain is the obvious next step and is not implemented. The local replay short-circuit persists for the lifetime of the ledger, while KeeperHub's own idempotency window is 24 hours — past that, the local ledger is the only thing between a repeated decision and a second transaction. Gas sponsorship is an observation from these runs, not a guarantee; do not size a treasury against it.

MIT licensed, 22 tests, no network needed to run them — seven of them drive bin/mcp-server.ts as a real subprocess over real stdio with the reference MCP client, and deleting the destination-allowlist check turns three of them red: bun install && bun test. The docs PR is a separate contribution to KeeperHub itself — the headless/agent onboarding path (SIWE sign-in, the undocumented signature_required step-up on API keys, and which address actually has to be funded), every claim re-verified live.