Security model

What it can reach,
and what it can't

WireHop hands a person or an AI agent real access to real machines. That is worth being precise about. This page is the honest version: the boundaries, how they are enforced, and where they stop.

If an agent is compromised What this doesn't protect you from

There is no WireHop server. WireHop is a tool you run, not a service you buy, so there is no account and no coordination service, and no company that could be breached to reach your machines. That includes us: we are not in the middle either.

If your AI agent is compromised

The fair question to ask about any tool that lets software run commands on your machines. Here is the actual answer.

An agent using WireHop holds exactly one thing: an invite that was issued to it. An invite is a single-use, time-limited token, and it carries the limits you set when you made it. It is not a master key, and it cannot grant itself more than it was given.

What a scoped agent can do

  • Reach only the machines its role permits, and nothing else on your network
  • Run only the commands you allowed, if you set an allowlist
  • Read only the paths you scoped it to
  • Work until the invite expires, then stop

What it cannot do

  • Escalate its own role, or mint invites, unless you gave it admin
  • Reach a machine whose tags its role doesn't cover: forwarding is default-deny
  • Write anywhere, if the invite is read-only
  • Act without a record: every machine keeps its own audit log

The practical advice: give an agent the least invite that works. A monitoring agent wants --tier client --read-only with two or three allowed commands, not a full member of your network.

Scoping an invite for an agent
# A monitoring agent: read-only, two commands, one machine, 1 hour $ hop invite --tier client --read-only \ --allow-command df --allow-command uptime --expiry 3600 # A deploy agent: scoped to one directory, no network egress $ hop invite --preset deploy --scope /var/www --no-network # See what it actually did, on the machine it did it to $ hop audit --since 1h

Two independent gates

Reach and confinement are separate questions, enforced separately. Both must allow an action.

Reachcan it connect at all?

Every member has a role (member, developer, ops, …) and every machine has tags. A packet is forwarded only if the sender's role covers the destination's tags. This is default-deny: a role with no tags reaches nothing, so a new member starts with no reach and gains it by being granted a role, not by editing a policy file.

Confinementwhat may it do once in?

A session runs inside an OS-enforced sandbox: Seatbelt on macOS, Landlock on Linux. It governs which commands may run, which paths are visible, and whether outbound network is allowed. A client can ask for more restriction than the host set, never less: the two policies merge to the stricter of each.

Privilegeas whom does it run?

The daemon may listen as root, but shells, commands, and file transfers all run as the ordinary user bound into the invite. That user is fixed when the invite is made and cannot be changed by whoever redeems it.

Recordwhat happened?

Every machine writes its own audit log of connections, sessions, commands, transfers, and denials. There is no central collector to tamper with or subpoena, and no telemetry leaves your machines. Read it with hop audit.

Everything an invite can restrict

Set these when you mint the token. They travel with it and cannot be widened by the recipient.

--tier client
Reach this one machine only. No membership in your private network.
--tier warren-only
On your private network (we call one a warren), but refused a shell on the host.
--tier node
Full member: reachable, with a virtual address and a name.
--tier admin
Member, plus the ability to mint invites and grant roles. Give this sparingly.
--read-only
No writes, deletes, or modifications to the filesystem.
--no-network
No outbound network from anything the session runs.
--scope PATH
Only these paths are visible. Repeatable.
--allow-command CMD
Only these commands may run. Repeatable.
--preset monitor|audit|deploy
Ready-made bundles of the above for common jobs.
--expiry SECS
How long the token stays redeemable. Defaults to 15 minutes.

Identity, transport, and the binary itself

What protects the connection, and what protects the thing you downloaded.

Identity is a keypair

Each machine has an Ed25519 key generated on first run and stored with owner-only permissions. There is no account to phish and no password to reuse. Losing the key is losing the identity, which is the point.

Encrypted end to end

Connections are QUIC with TLS 1.3 between your machines. When a direct path can't be punched through NAT, a relay forwards encrypted packets it cannot read. A relay sees that two machines are talking, never what they say.

Signed releases

Every published binary carries a SHA-256 checksum and an RSA signature. The installer verifies both against a key embedded in it and refuses to install on a mismatch. macOS packages are signed and notarized with Apple.

Invite tokens are hashed with Argon2 before storage, so the host keeps a verifier rather than the secret. Stored secrets are encrypted with ChaCha20-Poly1305. None of this has to be taken on faith. The implementation is public and permissively licensed, so you can verify it yourself, or hand it to a model and have it verify it for you.

What this does not protect you from

A security page that only lists strengths isn't a security page.

  • An agent acting badly within its limits. Scoping bounds the blast radius; it does not make an agent's judgment good. If you grant write access to a directory, an agent that decides to delete the wrong file in that directory can. Scope to what the job needs and read the audit log.
  • A compromised machine. If an attacker already has root on one of your machines, they have that machine's identity, and WireHop will treat them as that machine. Revoke it with hop fleet prune or an admin revoke.
  • An invite you hand to the wrong party. A token is bearer credential until it is redeemed or expires. Short expiries and single use limit the window; they do not close it. Treat an unredeemed invite like a password.
  • Sharing with people outside your control. WireHop is built for machines you own. It has no multi-tenant model, no per-customer isolation, and no SSO. If you need those, it is the wrong tool and we would rather say so.
  • Traffic analysis at a relay. A relay cannot read your traffic, but it can observe that two nodes exchanged packets and roughly how much. If that matters to you, run your own relay.
  • An unaudited codebase. WireHop has not had a third-party security audit. The code is public and the threat model is written down, which is not the same thing as an audit, and we are not going to imply otherwise.

Found something? Report it privately through GitHub's security advisories on the repository. We aim to acknowledge within 72 hours and will credit you in the release notes unless you'd rather we didn't.

Security policy Full threat model