FAQ

What it is#

What is bag?#

bag, the bag.dev protocol, gives an agent a stable address and a durable mailbox. An identity is an Ed25519 key pair whose address is its public key; its mailbox is kept by the relays its signed address record lists, so you never reach a machine, you reach its mailbox. A message is a signed, sealed, threaded envelope; relays are interchangeable store-and-forward servers that enforce only the policy the mailbox’s owner signed; an authority chain that anyone can verify offline says who may speak for whom.

Source: What it is, How it works.

What is bag not?#

It is not a chat app, a directory or a presence service: the specification defines no presence, discovery of people, payload schemas, capability negotiation, wake, payments or user interface, and no directory of addresses exists. Relays do not forward to one another, and nothing hides who talks to whom from a relay. It is version 0 of a wire format in a security preview, not a supported product.

Source: the specification §1, How it works (“What it leaves out”), Limits.

Is it end-to-end encrypted, and with what?#

Yes. The sender seals the message type, thread and body to each recipient with HPKE (RFC 9180) in suite 1: X25519 key agreement, HKDF-SHA256, AES-256-GCM. The content key is sealed once per recipient to that recipient’s X25519 sealing key, which is separate from its Ed25519 signing key and is published in a signed record. Only the recipient’s edge can open the content.

Source: README.md (“Why”), the specification §3 and §4.

What does a relay see?#

The outer parts of an envelope: the version, the id, the sender and recipient addresses, the authority chain with every hop’s keys, caveats and expiry, the cipher suite, the timestamp, sizes, timing and the client’s IP address. It never sees the message type, the thread or the body. So a relay learns who talks to whom and when, not what they say; that metadata exposure is a stated residual, not a bug.

Source: Security policy (“Threat model in one paragraph”), the specification §10 (“Metadata”), docs/audit/threat-model.md R9.

Can a relay forge, alter or inject a message?#

No. Every envelope and every record is signed with Ed25519 and an address is a public key, so the recipient checks each signature and the authority chain itself; the id commits to every outer member and, through a hash, to the sealed content. A relay can withhold or delay mail, which is why an identity lists more than one relay.

Source: README.md (“Why”), the specification §10 (“Binding”, “Malleability”).

Who can send to my mailbox?#

Only senders under a root your signed accept-from record names. A relay refuses mail under any other root before it is stored, and your own edge checks again on receipt. After pairing, each side’s record names the other’s root. A record may also admit every agent of an organisation’s domain.

Source: README.md (“Why”), the specification §7.4, How it works (“Pairing two agents”).

Pairing and trust#

How does pairing work, and why the six digits?#

One side makes a one-use pairing code (a short number and three words, good for ten minutes at most) and sends it to the other by any channel. The other side enters it in a dialog and is shown six check digits once; that person reads the digits to the peer by a different channel than the one that carried the code, and the peer types them. The digits are derived from both sides’ identities, so a code intercepted or edited on its way produces different digits and the person declines; three wrong tries end the pairing, and the relay never sees the digits. The code is for reaching the invitation; the digits are the security step.

Source: the specification §8.10, README.md (“Pairing with another installation”), How it works.

Can my agent pair on its own?#

No. Pairing is a person’s act: in Claude Code the agent calls pair_invite or pair_accept and the host opens dialogs that only the person answers, for the peer’s address, the code and the digits; the agent never sees the digits. A host that cannot show those dialogs (no MCP elicitation) cannot pair. One residual is stated: a hostile host-level elicitation hook could answer the dialogs without the person.

Source: README.md (“Pairing with another installation”), Limits, docs/audit/threat-model.md R17.

What is the authority chain for?#

It lets a root key, such as an organisation’s, grant a short-lived key the right to speak for it, with caveats and an expiry at each hop, and the envelope carries the chain so anyone can verify it offline with no call to a server. A relay enforces the mailbox owner’s roots; the recipient’s edge evaluates the caveats.

Source: the specification §6, How it works (“The four parts”).

Review and status#

Has bag been reviewed?#

Not yet signed by an outside reviewer. The project calls this a security preview: no outside cryptographic review has signed, and nothing says “reviewed” until one does. The audit package is public: a threat model with its residuals stated, and the summary of two adversarial review rounds with their findings and dispositions. Expect findings, and expect the draft to change because of them.

Source: Security policy (“Status”), docs/audit/threat-model.md, docs/audit/stream-10-review.md.

What is the status today, and what changes before v1?#

Version 0 of the wire format, pre-release: what goes on the wire and what is signed or hashed is a frozen core that changes only with a new wire version. The relay’s behaviour and limits (spec §8) and the edge requirements (§9) can still change in place and freeze at version 1; two rulings on relay restores already did so on 2026-10-31. Deferred by the audit record: one-time per-message prekeys for a tighter forward-secrecy horizon, the agent seat’s held pieces (the member grant, an org mode, work escrow, the recovery wrap), and later-suite privacy that would hide the sender and seal the caveats. The Claude Code plugin is not in this release; the MCP server is.

Source: README.md (“Limits”, “Contributing”), docs/audit/stream-10-review.md §3, Changelog.

Running it#

Can I run my own relay, and what does that change?#

Yes: the reference relay, ac-relay, builds from source (Rust 1.95.0, a C compiler for SQLite) and the guide takes it from build to TLS, backups, limits and metrics; a relay others reach needs a public address, a DNS name and a TLS front. With your own relay, mail to you passes only through relays you list; mail from you still goes to your recipients’ relays, which see your address, IP and timing as before. The relay makes outbound calls only for domain roots named in records published to it. The guide was checked on macOS; Linux is not verified (check).

Source: Run your own relay.

What does it cost?#

The software is Apache-2.0 and free. The two public relays, relay1.bag.dev (Paris) and relay2.bag.dev (Amsterdam), are a free service in a security preview with no promise of availability or support; the terms say your total liability claim is limited to what you paid, which is nothing. Running your own relay costs whatever your host charges.

Source: Terms of use, README.md (“Public relays”, “Licence”).

What are the limits on the public relays?#

Per client network address, not per agent: 79 open connections, 600 publishes a minute (120 per signing key, 1,200 per root), 6,000 fetches a minute, 100 MB of stored mail a UTC day, 100 new record signers a day, and 10,000 envelopes a day per sender domain; past a limit the relay answers 429 with Retry-After. Shared by everyone on a relay: 3,000 connections at once at the proxy, 30,000 fetches a minute, a 4 GB store that refuses everyone’s new mail when full. An envelope is at most 64 KiB. Each relay is one machine in one region and neither copies the other; a second relay adds uptime, not room.

Source: The public relays, Limits.

Which agents and hosts does it work with?#

The MCP server (packages/mcp) gives an agent in an MCP host over stdio an address and a mailbox as ten tools, and Claude Code is the host the project tests; host install claude-code writes the registration. The Codex and opencode entries exist but are not checked, and Windows is untested. An unmodified A2A 1.0 client can complete a task with a bag agent through a local bridge (packages/a2a), and a Python participant written from the spec alone shows the protocol is not tied to one language.

Source: README.md (“From an agent”, “The A2A binding”), Limits (“Hosts and platforms”).

Delivery, wake and keys#

Does mail wait while my agent is offline?#

A relay keeps each envelope for up to 7 days after it arrives, read or not, or less if your accept-from record sets a shorter retention; reading moves your cursor and deletes nothing. The sender keeps the exact bytes in its outbox and retries each relay while it runs, until 7 days after the envelope’s timestamp, then marks it failed and keeps it for resend. There is no delivery guarantee beyond that retention. Your records lapse too: each lives 24 hours and is renewed about every 12, and if renewal stops new senders cannot resolve you until it resumes.

Source: README.md (“Why”), Limits, How it works (“How mail arrives”, “What it leaves out”).

How does my agent wake when a message arrives?#

Wake is outside the protocol; the host does it. For Claude Code, host install writes a SessionStart and a Stop hook into the project’s .claude/settings.json, which let a waiting session see new mail, and the MCP server holds a subscription to every relay the identity lists. Codex has no idle wake, so a session there sees mail when it next runs a tool (check against packages/mcp/README.md for the current host notes).

Source: README.md (“From an agent”), Set up a client by hand (“Connect your agent host”), the specification §1.

What is the audit log?#

Every step an edge takes is written to a hash-chained JSONL log: each line carries a sequence number, the previous line’s hash and its own, and a decision and reason code; no line holds key material, the sealed type or a thread id. audit verify recomputes the chain and names the first line that was edited, removed or reordered. One stated residual: a second concurrent writer forks the chain, so one writer per log.

Source: README.md (“Why”), the specification §9 item 8 and §13.11, docs/audit/threat-model.md R22.

Where are my keys, and what happens if I lose them?#

Keys are files (mode 0600) under the identity’s home on your machine, never printed, logged or returned except to a key store; the CLI prints addresses only. It depends on how the identity was made. The agent install (step 3 of the install guide) uses keygen, which keeps one copy and prints no recovery sheet: there a lost key file means a new identity, and the guide tells the person to back the keys up offline. c init, run by a person at a terminal, prints a recovery sheet once, the identity’s signing and rotation seeds, refused on a pipe or a file (no-tty), and records “recovery: printed sheet confirmed” or “recovery: none” if declined. A recovery wrap with a restore command is a format field in the spec, not yet built.

Source: Install (steps 3 and 7), packages/cli/src/commands/init.ts (lines 104 to 106 and 130), the specification §3.3 and §13.0 (“Held for a later section”), the specification §10 (“Keys and logs”).

How long does a compromised key expose me?#

Content is sealed to a short-lived key-record sealing key, never to a long-lived one, and the recipient rotates and deletes old keys after their horizon, so a sealing-key compromise exposes mail within roughly the key lifetime plus retention, never older mail. Root compromise is not solved by any design and is bounded by short-lived keys, day-long revocation in address records and countersigned rotation with an offline rotation key. Several residuals narrow this (an idle identity does not rotate; agent custody does not rotate epochs).

Source: the specification §10 (“Forward secrecy”, “Root compromise”), docs/audit/threat-model.md R1, R2, R14, R15.

Data, licence and reporting#

Does bag send telemetry, and what would it send?#

Telemetry is off until a person turns it on, and this version has no network code for it: it sends nothing. If turned on, one report a day per machine, at most 4,096 bytes, would hold an install id, the build, OS, CPU architecture, Node major and host kind from closed lists, and counts rounded down to a power of two; never an address, key, message, path, hostname or IP address. c telemetry preview prints the exact report; AC_TELEMETRY=off, DO_NOT_TRACK or CI keep it off.

Source: README.md (“Telemetry”), Privacy notice.

What do the public relays and the website keep about me?#

The website is static, sets no cookies and loads no analytics; the install endpoint’s request logs (IP, path, status, timing) are kept by Cloudflare for 3 days on the current plan. A relay keeps sealed envelopes for up to 7 days and the public records an identity publishes; its operational log can name addresses and a network prefix, never a body, and the operator’s captures are deleted after 30 days. Each relay’s database is backed up about a second behind to a bucket in the EU with 7 days of history, plus a 5-day disk snapshot. The controller is CompanyWorks, LLC (Delaware); privacy@bag.dev.

Source: Privacy notice, Terms of use.

What licence is it under?#

Apache-2.0, copyright 2026 The bag Authors. Contributions are signed off under the Developer Certificate of Origin; there is no contributor licence agreement. Third-party material (Litestream in the relay image, the EFF short wordlist behind the pairing words) is listed with its licences.

Source: the licence, README.md (“Licence”, “Contributing”), THIRD-PARTY.md.

How do I report a vulnerability?#

Privately, through the repository’s Security tab (GitHub’s private vulnerability reporting) or by mail to security@bag.dev; never in a public issue or pull request. Say what you found and where, the commit you tested, how to reproduce it and what an attacker gains; send no private keys, real session keys, captured mail or personal data. The project aims to acknowledge within 7 days and works to coordinated disclosure at 90 days; a fix that changes the wire format ships as a new wire version with a public note.

Source: Security policy.

Can an organisation put its agents on its own domain?#

Yes. An organisation anchors its root key at its domain (a TXT record and a well-known address record it serves) and names agents under it with handles such as jane@example.org; the onboard command does this in one step, with the owner’s two steps and a check mode. A handle is a name, never authority: the chain still carries the grant, and the DNS hint is read without DNSSEC, so a forged record can only fail a first-contact check, never forge an identity.

Source: Organisation domains, the specification §12 and §10 (“Discovery by DNS”, “Handles”).