How to use AgentBee

Everything you need to know: what's in the box, setup, connecting it to your AI, the tap-vs-hold trust matrix, and how every approval becomes signed, verifiable evidence.

⚙️Getting started

What is AgentBee?

A small hardware key that makes a human approve the critical actions an AI agent tries to do. The agent proposes; you approve on the device with a tap or a hold; you get a signed receipt. It is authorization, not authentication — it sits next to your YubiKey, it does not replace it.

What's included?

The AgentBee key (a compact device with a 1.47" colour screen and a button) in its case, and a USB cable. The software is pre-loaded — there is no app to install and nothing to flash. Setup is one page in your browser.

Is the software pre-loaded?

Yes. The firmware ships pre-loaded and locked. You never flash it. The first time you set it up, your signing key is generated on the chip itself and never leaves the device.

How do I set it up? (onboarding)

Plug it into USB and open setup.agentbee.co.uk in Chrome or Edge.
It runs a genuine check — confirms the device is real and untampered against the AgentBee Root held in our HSM.
It creates your key on the chip. The private key never leaves the device and never reaches us.
Pin it — hold the button to confirm — so only your bee can approve your actions.
Connect it to your AI with one command.

No accounts, no cloud, no key escrow. We keep no keys and nothing about your device. The only thing setup runs is in your browser.

🔌Connect & use

How do I add it to Claude, OpenAI, Qwen, DeepSeek…?

AgentBee is MCP-native, so it works with any MCP-compatible client.

Claude — one command: claude mcp add agentbee -- npx -y @agentbee/mcp. Or, with the AgentBee skill, just ask: "Gate my critical actions with AgentBee."
OpenAI / Qwen / DeepSeek / any MCP client — add the same MCP server in your client's config.
Anything without MCP — use @agentbee/sdk (one call) or a hook (git pre-push, a command wrapper, a CI step).

Add the AgentBee skill (the easy way)

With the skill installed you do not configure anything by hand. You just tell your AI what to gate, in plain English.

Install the skill. Put the agentbee skill folder where your AI looks for skills:
- Claude, everywhere: ~/.claude/skills/agentbee/
- Claude, this project only: .claude/skills/agentbee/
The folder holds SKILL.md, scripts/ and trust-map.json. It ships with your bee.
One-time setup. Make sure Python is ready (pip install pyserial cryptography), then plug in your bee and pin it: python3 ~/.claude/skills/agentbee/scripts/agentbee-gate.py --pin (hold the button to confirm it is your key).
Use it. Just say:
- "Gate my critical actions with AgentBee."
- "Make me approve pushes to main on the bee."
- "Show my AgentBee receipts this week."

No config files. The skill wires the right hook or gate for whatever you ask, and the bee does the rest. For OpenAI, Qwen, DeepSeek or scripts, the skill is the Claude convenience layer; everywhere else the same gate runs via MCP or a hook, with the same bee and the same receipts.

How do I use it day to day?

When your AI tries something that matters — delete a database, move money, deploy, push to main, use a secret — the bee lights up and shows the exact action on its screen. You approve or deny on the device. Approved actions proceed with a signed receipt; denied ones never run.

The trust matrix: short press vs long press

The gesture is graduated to the risk, so you are not interrupted for routine things and you cannot fat-finger a dangerous one.

Action risk	To approve	To deny
L0–L2 (reads, routine writes)	a quick TAP	hold, or ignore
L3–L4 (deploys, payments, deletes, prod pushes)	a deliberate HOLD (~1.5s)	tap, or ignore

Short press (tap): approves low-risk actions, and denies high-risk ones.
Long press (hold): approves high-risk actions (a progress bar fills), and denies low-risk ones.
The device tells you which it wants, each time. Ignore it and it times out, blocked.

Why two gestures: an accidental tap can never approve a destructive action — approving the dangerous stuff always needs a conscious hold.

🧾Evidence & proof

How are my AI's actions evidenced?

Every approval is signed on the device with a key that never leaves it, and recorded to a local, append-only ledger. Each receipt proves what was approved, on which device, and when. Here is a real one, exactly as stored:

{"action":"Delete GH prod DB","scope":"prod-main","trust":"L4",
 "result":"approved","ts":"2026-06-09T08:39:01Z",
 "sig":"15050fde…c91dfb1","device":"3166993cc2f863e3"}

How do I prove what my AI did, later?

Ask in Claude: "show my AgentBee receipts this week", or run agentbee-gate.py --ledger week. It lists every approval and re-verifies each signature against your key — provable proof you approved it, checkable offline by anyone holding the public key. No server, no account, no trust in us.

Is it tamper-proof?

It is tamper-evident — and that is the stronger, honest claim, because nothing is truly tamper-proof. Two layers make tampering detectable:

Each receipt is signed over the exact action. Change one character of what was approved and the signature stops verifying.
The ledger is hash-chained — each entry carries the hash of the one before it. Remove or insert a record and the chain breaks.

So nobody can forge a receipt, and nobody can quietly edit or delete one of yours without it showing.

🔐Security & recovery

What about the key and security?

The private key is generated on the chip and never leaves it.

Not over USB, not over Bluetooth, not to any cloud. There is no copy anywhere.
On locked units it is non-extractable (Flash Encryption + Secure Boot v2), the same protection class as a Trezor One.
No cloud, no escrow, no recovery, so there is nothing to breach or phish.
The public key is meant to be shared. Sharing it is harmless.

It is not "unhackable" — nothing is — but extracting a key would need physical possession, lab equipment, time and money, for one device, not a fleet and not remotely.

Lost it, broke it, or got a replacement?

A replacement bee sets up exactly like your first one. There is no special "recovery" to learn. You plug it in, run the quick setup, and it is yours. About a minute.

Plug in the new bee

Connect the replacement (or a spare) to your computer with the USB cable.

Run the setup page

It checks the bee is genuine and creates its key on the chip.

Hold the button

When it asks, press and hold the bee's button for a second. That makes it your key.

That's the whole thing. The new bee is now the one your computer trusts. And three things stay true: every action you approved before is still provable (your receipts never expire); the bee you lost can't do anything on its own, because it only ever responds to your own computer; and there is no master password or backdoor, by design. Want zero downtime? Set up a spare bee now and keep it safe — if you lose your main one, the spare already works, with nothing to do.

Do I have to reconnect it to Claude when I replace it?

No. Connecting AgentBee to your AI is a one-time setup on your computer, and it works with whatever bee is plugged in. A replacement is just new hardware, so the software on your computer does not change. You only set up and trust the new bee (plug in, run setup, hold the button).

Using Claude, you would just say: "I've got a new AgentBee, set it up." You never re-run the connect command. The one exception is a brand-new computer, where you set the software up again and then trust your bee.