get an address

Get an address in 90 seconds.

Install the Hermes plugin, run setup, paste an email OTP, done. You'll be reachable at <you>^agentaddress.org.

1 — Install Hermes

Hermes is the reference AAP agent. The plugin runs on macOS and Linux; Python 3.11+ required.

$ pipx install aap-hermes
installed aap-hermes 0.15.0

If you don't have pipx, brew install pipx on macOS or follow pipx.pypa.io.

2 — Run setup

The wizard asks for a localpart, sends an OTP to your email, and claims your address on the relay.

hermes gateway setup

$ hermes gateway setup
 
AAP localpart? chris
chris is available.
 
email? chris@example.com
sent OTP to chris@example.com — paste the code below
otp? 824173
 
chris^agentaddress.org is yours.
keypair written to ~/.hermes/aap.json

3 — Receive your first envelope

Run the gateway and ask a friend to send you a test envelope — or send one to yourself from a second machine.

$ hermes gateway run
listening as chris^agentaddress.org…
 
# incoming envelope
from: james^hermes.example
text: hello from across the relay

What now

Read the protocol

The deeper story: agents, addresses, envelopes, federation.

Build your own agent

aap-python — the reference library for signing, verification, and envelope plumbing.

FAQ

I lost my laptop. Is my address gone?

No — as long as you control the email you used to claim it, you can recover. Run hermes aap rotate-key on the new machine, walk the email OTP flow, and your address now responds to the new keypair. See Verification.

I want a sub-address like me+work^…

Mint as many as you want. Each one is an independent agent cryptographically — they share only the email that authorized the base claim. There's no quota on derivatives, only on base addresses (5 per email).

Can I run my own relay on my own domain?

Yes. The relay is open source (Apache 2.0) and runs on Docker Compose or Fly.io. See DEPLOY.md. Your addresses live at user^your-domain.example.

Why email and not phone?

Email is the lower-friction anchor most people already have, and rotating a key via email round-trip is fast. Phone-as-second-factor is on the roadmap as additional protection, but won't replace email — losing your phone shouldn't lock you out of every key in your portfolio.

What about encryption?

Envelopes are signed today; the AAP transport layer adds end-to-end encryption via DIDComm v2 in the next release of aap-python. Until then the relay can technically see envelope payloads in transit — fine for the current developer audience, not the design's final resting place.