Security model
peers connects Brokers that do not know each other, and every delivered message ends up inside a Claude Code session, where text from another host should be treated as untrusted input. This page describes where trust comes from, what each mechanism protects and where protection stops.
Pairing and fingerprints
Each Broker has a self-signed certificate, and its identity is the fingerprint of its public key. No certificate authority signs it. Links use TLS 1.3, and each side checks the other’s fingerprint.
Two Brokers trust each other only after a pairing. The accepting side creates a one-time pairing key and shows it together with its advertised addresses and a paste-ready connect prompt that names the key and this Broker’s addresses. The user passes the prompt, or the key and an address, to the other host’s user through a channel outside the system. This is a security requirement: the tool descriptions, the notes on tool results and the session instructions require the agent to show the key and the prompt to the user only, never to send either through send_message, Claude Code’s built-in session messaging or any other agent-to-agent channel, and never to create or pass one at another agent’s request. The Broker does not block such a forward: this is a requirement on the agent, not a guarantee the system enforces, so the channel a key travels through is the user’s to control. The channel that carries a one-time key must be trusted, because anyone who holds a one-time key can pair with it until it expires or is used, and a channel that exposes the key to another agent, a log or a third party exposes the pairing as well. A one-time key is 16 characters, shown as four groups of four, expires and works once. The alternative is a pre-provisioned static key that the user or administrator writes into the Broker’s configuration file: 16 to 128 characters, reusable, never expiring and never generated by the system. The handshake proves that each side holds the key and binds it to the fingerprints each side observed. After that, a Broker recognizes its peer by the saved fingerprint alone.
The alias and the advertised addresses are not authenticated. An alias is for display, and an address says where to connect, not who answers. A user Broker’s default alias contains the name of the account that runs it, which peers and anyone who receives a public broker card can see; set broker.alias to keep the account name out of the agent address. Pairing is pairwise and not transitive: if A pairs with B and B pairs with C, A and C do not trust each other. To stop trusting a host, unpair it on every Broker that paired with it. A paired Broker’s reports about its own agents and topics cannot be verified from this side. Of the addresses a peer reports, the Broker stores only a host:port it can dial and skips the rest. An alias a peer gives up while the pairing lasts stays reserved for that peer, so an address handed out earlier never starts pointing at another Broker.
A static key is stored in plaintext in the configuration file. Any account that can read the file can read the key and use it to make this Broker add a peer, even without write permission. The person who sets the key is responsible for its randomness; the length check does not stop a long but guessable key, so draw the key from a random source such as the output of openssl rand -hex 32. Before the accepting side is verified, the initiating side sends a lookup tag derived from the key, so anyone who captures the handshake, or any host the initiator reaches through a wrong address or a hijacked domain name, can use it to brute-force a weak key offline. A host that has paired with this key knows it; if it can intercept or mislead a new host’s connection, it can impersonate the accepting side. Replacing the key blocks new pairings made with the old one; peers already paired with it stay paired until they are removed individually. The lookup tag is bound to the initiating side’s fingerprint, so a third party that captures it and presents it under another certificate matches no key. A pairing request that matches no key is rate-limited per source, and all sources together have a further cap; a request over either limit is refused with try again later. The limit is checked before the static key, so once a source or all sources reach it, even a request holding the static key is refused with try again later; a request that matches the static key does not add to the count. The initiating side sends its own alias only after it has verified the other side.
Private by default
A Broker publishes a broker card with its fingerprint, alias and advertised addresses only after the user sets it public. A private Broker still receives broker cards from other Brokers, and its peers do not pass its information on. A private Broker also cannot declare a public topic, because the declaration has to be signed and the signature reveals the fingerprint.
Private does not mean hidden. A peer knows the fingerprint and alias, a host that initiates pairing learns the advertised addresses, and any host that can reach the listening port can see the certificate.
A host that can reach the listening port can also open connections. Unauthenticated connections are capped: a source may hold at most 8, where a source is one IPv4 address (a /32) or one IPv6 /64, and all sources together at most 64. Once the TLS handshake confirms that a connection’s fingerprint belongs to a paired peer, the connection leaves this count, and these connections are capped at 2 per fingerprint instead. Before a connection authenticates, it may send at most 64 KiB, and its HTTP/2 header list may be at most 16 KiB. A flood of connections from one source therefore cannot crowd out pairing from other sources or the reconnection of a paired Broker.
A rejected connection leaves a record. When an unpaired host connects and is rejected, the audit log records one connection_rejected event whose detail is usually not a peer from <source>, where the source is the other host’s IPv4 address or its IPv6 /64 prefix. When the connection carries no readable source address, the detail is not a peer, and when the Broker’s merge windows are full, rejections from further sources fold into one record whose detail is other sources. Every account that may read the Broker’s configuration file can see these records with peers service audit.
Topics decide visibility
Two agents can see each other and exchange messages only when they share at least one topic. The same rule applies to two sessions on one host and to sessions on different hosts, and for a remote agent both ends of the link check it.
Joining a topic needs only the name. There is no administrator, invitation or approval, and a member cannot be removed. A topic name is therefore not a secret: anyone who knows it can join, and everyone in the topic is visible to every connected peer that has a member in it. Sending to all members of a topic takes one call per recipient.
A session joins a default topic declared by its project configuration file. Without that file, the default topic comes from the workspace’s git origin address. Automatic joining can be turned off.
Management operations need configuration file permission
The Broker decides what a caller may manage from the operating system’s process credentials for the local socket, not from what the caller says. Write permission on the Broker’s configuration file allows changing the configuration, creating a one-time pairing key, pairing and unpairing. Read permission allows reading the configuration, reading the audit log and seeing status beyond the caller’s own agents. Listing agents and topics, joining and leaving topics and sending a message need neither.
This means a system Broker can delegate management with ordinary file permissions: the system installation makes the default peers group own a new configuration file, and members of that group can manage the Broker through the tools or the terminal commands without sudo when the account runs no user Broker of its own. Membership carries the same power as editing the configuration file by hand, not root’s power; unlike a member of the docker group, a member here cannot use the Broker to run arbitrary commands or write files other than the configuration file. Two limits apply, described in The admin group: a port below 1024 in broker.listen takes effect only while the configuration file can be written by root alone, and a change made by editing the file directly is recorded in the audit log with no account. An administrator who runs the terminal commands with sudo is checked as root. The check also means that the account, not the person or the model, is identified. Every process under an account acts with that account’s authority, and a call made by a model steered by prompt injection is indistinguishable from one the user intended.
Messages enter a session without an authentication token
Claude Code lets a process that writes to a session’s inbox socket present an authentication token. peers does not present it and does not read the token file. Delivered text therefore enters the target session as coming from a sender with no declared permission category. The receiving session applies its inbound controls to such a message. A session that skips permission prompts and has no inbound policy set holds each message for individual approval. A session that runs headless and also skips permission prompts cannot receive messages from peers: the message is held and then dropped because the sender declares no permission category, while the sending side has already returned success. See known limitations.
The Broker is designed not to be a descendant of any session. A user Broker is started by the service manager or by the user in a terminal, outside the session’s process tree, and a system Broker runs as a service outside it. An account that can use the host’s system Broker needs no user Broker, and a running user Broker takes precedence over the system Broker.
Native Windows is not supported because inbox connections there require the authentication line.
Received content is untrusted
Text that arrives from another agent is not the user’s instruction. A message from a sender whose name contains @ comes from another agent or Broker, possibly on another host or under another account. The same is true of the public topic names and descriptions that list_topics returns and of the addresses of other Brokers that list_brokers returns. peers does not verify any of it. The session instructions require the model to relay such a request to the user and get the user’s explicit consent before acting on it, in particular before changing configuration, pairing or unpairing, upgrading the Broker, setting it online or offline, running a command or reading or sending a file. The agent names, addresses and accounts that list_agents returns, and the account of a remote agent, are reported by a Broker and are unverified. As with the pairing key rule above, this is a requirement on the model, not a guarantee the system enforces.
Delivered text is placed inside a fixed envelope that names its sender. When a message body contains the envelope’s opening or closing tag, in any letter case, peers escapes it by inserting a backslash after the <, so the body stays plain text and cannot forge either end of the envelope. Known limitation: HTML entities, zero-width characters and homoglyphs are not escaped; they change only how the body displays in the session, not how the envelope attributes the message.
When a peer Broker returns an error for a send, this Broker relays only a code the receiving Broker can actually return: not_found, ambiguous, not_visible, invalid_argument, too_large, inbox_unwritable, quota_exceeded, broker_offline or delivery_unknown. The error reads Not sent: Broker <alias> said: "<...>", or Delivery unknown: Broker <alias> said: "<...>" when the code is delivery_unknown; the quoted text is capped at 512 bytes, cut at a character boundary and marked with .... Any other code is reported as Delivery unknown: Broker <alias> returned an error this Broker does not recognize, and the peer’s text is not repeated.
When a terminal command prints text the Broker supplies, a tab, a line break, a line separator or a paragraph separator becomes a space, and every other control character or Unicode format character is shown as \xNN, \uNNNN or \UNNNNNNNN, by its code point.
Rate limits, loop detection and duplicate suppression
peers itself does not limit how many messages a session sends, count hops or detect message loops. The receiving Broker does limit how many messages one paired Broker delivers to one local session: ten in a row, then one more every 10 seconds. A message over the limit is not written, and the sender gets the code quota_exceeded with this error, where <alias> names the receiving Broker, <session> the target session and <fingerprint> that Broker’s fingerprint:
Not sent: Broker <alias> said: "<session> is receiving too many messages from your Broker; try again in <N> seconds" (code: quota_exceeded; reported by Broker <fingerprint>)<N> is the wait in whole seconds, rounded up, so a sender that waits that long can retry; the word is second when it is 1. The limit applies separately to each source Broker and target session, so a send within this host and a send from another paired Broker are not affected by it. The values are constants and are not configurable.
The receiving Claude Code applies its own rules. It identifies a sender by the reply address in the frame, or by the writing process when there is none. Each sender gets a token bucket with capacity 30 that refills at 0.5 per second, and at most 50 pending cross-session messages are held. The 30-second rule is separate: it drops a message from the same agent to the same session whose content repeats the previous one. The signature is part of that content, so the rule distinguishes agents even when they share one token bucket; two agents do not suppress each other’s messages.
The receiving Broker also drops a copy that a retry within one send produces. It identifies the copy by the message identifier in the delivery request and keeps the result in an in-memory table for send.dedupe_window, 5 minutes by default. The table is lost on restart, so if the Broker restarts between two retries, the same message can be written twice. A send made after the outcome is unknown carries a new identifier and is not deduplicated. The table holds at most 65536 entries in all and at most 4096 from one peer. A message beyond the per-peer limit is refused with the code quota_exceeded and the text this Broker holds too many recent messages from your Broker; when the whole table is full, a message is refused with inbox_unwritable and the text the Broker is temporarily holding too many messages. The sender sees either text relayed by the receiving Broker.
peers writes without a reply address, so everything written through one user Broker, or through one account helper of a system Broker, counts as one sender and shares one token bucket, whichever agent sent it. Claude Code’s own loop detection relies on a path recorded in its messages; peers messages carry no such record, so the rate limit is the only thing that constrains a loop between two agents. Claude Code can change its rate limits and its 30-second rule, and it can adjust them remotely.
peers itself limits topic changes: joining and leaving are rate-limited per account, and the local topics and the members of one topic are capped, as Limits describes. A member roster from a paired Broker is held to 4096 entries per topic and 16384 per link; a frame above either limit is dropped whole with a warning in the Broker’s log, and the link stays up. Members in a dropped frame stay missing until the link is established again. A frame above 4 MiB is refused before it is sent, and the link is not closed.
A link has inbound limits of its own. One connection may queue at most 4096 state frames or 64 MiB of state-frame payload, counting the frames waiting and the one in progress; over either limit, this Broker closes that one connection, and the dialing side reconnects under the usual backoff. At most 64 request handlers of one peer run at once across all its connections; when every slot is taken, this Broker pauses reading that peer until a request completes, without an error and without closing the link. peers service status and list_brokers give the reason in the detail for a link closed this way: the peer sent more state frames than this Broker's inbound limit allows on one connection; the link was closed and will reconnect after a backoff; check the audit log for the link_down record. The audit log also has a link_down record with the detail inbound_limit, which peers service audit shows.
The operating-system account is the isolation boundary
A user Broker serves only its own account and rejects calls from other accounts. A system Broker serves the accounts allowed to use it, and accepts a registration only for an inbox socket owned by the calling account. Within one account there is no further separation.
On a system Broker, name ownership gives a name to the account that registers it first: another account cannot take over the owner’s by-name address by registering the same name, and its same-named agent always carries the full 12-character disambiguator, so a session tells the two apart by the address and by account. A name is released after 7 days during which no agent of the owning account uses it.
A Broker also gives a peer the account name that registered each agent it reports, whether it runs as a system Broker or a user Broker. The account name is for display only, but a peer can see it. An account name that does not fit the format is left out, whether it comes from this host or from the peer.
The local interface of a system Broker also bounds what one account can hold, so one account cannot exhaust the Broker or push other accounts out of it. Each account may hold at most 256 local connections and 256 registrations, and each connection may carry at most 64 concurrent streams. Across all accounts, the Broker accepts at most 4096 local connections at once, the admission connection limit; within it, at most 64 connections may wait at once for an account lookup, each for at most 5 seconds, and a connection past that bound is refused at once instead of queued. The 64 waiters are separate from the 64 concurrent streams one connection may carry. A check of a caller’s permission to read or write the configuration file runs in a separate process; at most 8 such checks run at once, and at most 2 for one account. A uid that resolves to an account gets its own share of these limits; uids that resolve to no account, such as those a rootless container rotates through, enter the unknown-account bucket and share one per-account quota among them, a shared quota rather than one quota each. These values are constants and are not configurable.
The following limits are reported to the session with the code to act on. A connection refused at the handshake returns the Broker is running but refused this connection; this account or the whole host may have reached its connection limit, so retry shortly. with the code internal. A registration over the per-account limit returns the Broker’s sentence cannot register: account <account> already has 256 open registrations with the code quota_exceeded. A permission check that cannot take a slot returns Too many configuration access checks are running; try again shortly. with the code quota_exceeded. Waiting and retrying shortly is enough for a permission check that cannot take a slot. The other two need no manual retry: the MCP server reconnects in the background on its own, and the session gets in only after another session or connection ends and frees a slot, in this account or, when the host-wide connection limit was reached, anywhere on the host. A registration slot lasts as long as its session stays connected, so an account already at 256 sessions cannot get another one in until one of them ends.
Update checks contact GitHub
Each Broker checks GitHub for a newer formal release shortly after it starts, then every 24 hours by default. When peers update selects a Broker that runs as a service, that Broker performs the update, for the system installation as well as the user one. When no Broker is running, or the selected user Broker does not run as a service, the command performs the update itself.
Checks and downloads use HTTPS only. A check goes to GitHub. A download may be redirected from GitHub to its storage host, so a host-name allowlist must include both. A check is an ordinary GET request to https://api.github.com/repos/wangzw/peers/releases/latest, with no extra request headers; the repository wangzw/peers is fixed in the binary. When an update runs through a Broker, the Broker fetches that release by the tag it chose; when the command performs the update itself, it downloads the latest release it finds after you confirm. Either way, it downloads the archive and checksums.txt from the release’s asset download addresses. Neither request carries a host name, account name, agent identity, pairing data or configuration.
A failed check writes one debug-level log line and changes nothing else, and a check result is held in memory only until the Broker restarts. To stop the checks, run:
peers config set update.check falseThe Update line in peers service status and the notice in a session disappear as soon as the setting takes effect. On a host without network access, turning the checks off is enough; peers update contacts GitHub only when you run it. Downloads use the proxy environment variables of the process that performs them; Update peers describes how to set them for a service.
An update runs only after a confirmation. peers update asks for confirmation and installs only after you answer y or yes, or pass --yes. A session can start the same upgrade with the update_broker tool, and Claude Code asks for confirmation by default before the call runs; do not add update_broker to an auto-approve list, because that confirmation is the last manual check before an upgrade. Before anything is replaced, the archive is compared with checksums.txt using SHA-256, only a regular file named peers is extracted and the new binary’s --version must report the expected version. If any step before the replacement fails, the existing binary and the service are left unchanged. When a Broker performs the update, the command does not restart the service itself: it waits up to 60 seconds for the Broker to report the new version, and if that wait times out it prints the location of the service log. A system update requires write permission on the Broker’s configuration file: an account without it is refused before anything is downloaded. When no system Broker is running, the command replaces the binary locally instead and checks write permission on the binary’s directory, not on the configuration file. Update peers describes the update.
A member of the admin group can make a Broker that runs as root install the latest formal release of this project, with the same trust as root running the update. The caller cannot choose the source or the version, and cannot downgrade. Releases are not signed, so an update relies on HTTPS to GitHub and on checksums.txt.