Getting started — using the App

This is the guide for someone who wants to use AI Agent Messaging Gateway, not build it. Contributors start at development.md.

The App is a chat workspace for your own agent. You run the agent on a machine you own; the Gateway routes and stores the conversation, the run lifecycle and the event log, and never runs your agent's reasoning, tools or model calls.

What you need

Item	Detail
Phone	Android. There is no iOS build and no store listing yet.
Agent runtime	Hermes on a VPS or laptop, Node.js 22 or newer.
Account	An email address. You create the account in the App; there is nothing to buy.
Gateway	The deployed production Gateway at `https://aamg-api.azuddin.com` (or your own deployment).

The whole flow

flowchart LR
  A["1. Install the App<br/>signed APK"] --> B["2. Create an account<br/>email + password"]
  B --> C["3. Connect your Hermes<br/>npm package + approve the pairing"]
  C --> D["4. Send a message<br/>watch it stream, close the App"]

1. Install the App

Download the APK from https://aamg-download.azuddin.com/index.html and open it. Android asks you to allow installing from this source: the App has no store listing, so that prompt is expected.

2. Create your account

Open the App and sign up on the sign-in screen with an email address and a password. That account is yours for the App and for the web client once it is served from the Gateway origin.

3. Connect your Hermes

On the machine where Hermes runs:

npm install --global @azuddin/aamg-hermes-adapter
hermes-connector connect

connect creates a keypair on that machine, asks the Gateway for a pairing request, and prints a QR code plus a copyable amg://pair?... link. The link is one-time material and expires after five minutes; it never contains a permanent credential.

sequenceDiagram
    autonumber
    actor You
    participant App
    participant Gateway
    participant Hermes as Your Hermes
    You->>Hermes: hermes-connector connect
    Hermes->>Gateway: Create pairing request
    Gateway-->>Hermes: Pairing link (5-minute, one-time)
    Hermes-->>You: Terminal QR + copyable link
    You->>App: Scan with the phone's Camera app
    App->>You: Show the agent identity + this Gateway's origin
    You->>App: Approve
    Hermes->>Gateway: Sign the proof of possession, complete
    Gateway-->>Hermes: Device credential
    Hermes->>Gateway: Connect outbound and stay connected
    Gateway-->>App: Agent connected

Scan the QR with your phone's own Camera app — the App deliberately ships no scanner. Before you approve, check the two things the screen shows you:

the agent identity — the Hermes you meant to connect;
the origin — it must be the same Gateway the Connector printed. The Connector prints the origin it selected; an origin the App is not configured for fails closed on both sides instead of silently switching servers.

There is no API key to paste, no port to open, and no credential shown on screen. Your machine dials out to the Gateway; the Gateway never dials in.

Keep the Connector running after the pairing:

hermes-connector service install   # user-owned service: no root, no inbound port
hermes-connector status            # paired origin, agent identity, connected state

status never prints a credential. Its exit codes make it usable as a monitor check: 0 connected, 1 paired but not connected, 2 the Gateway refused this credential (the device was revoked), 3 not paired yet, 4 protocol-version mismatch.

4. Send your agent a task

Open a conversation, type a message and send it. The reply streams in as the agent works. While it runs you can:

close the App — the run keeps going on your machine, and the result is waiting when you come back, with the events you missed replayed in order and without duplicates;
get a notification when the agent needs you or a run reaches a terminal state;
answer inline when the agent asks for an approval or a piece of input: the run is blocked on that answer, and it continues in the same turn.

Housekeeping: revoke, re-pair, recover

What you want	What to do
Stop using a machine	Revoke the device in the App. The Connector stops reconnecting with that credential, fails closed, and asks you to pair again.
Pair a machine again	`hermes-connector connect --re-pair` — a new pairing request and a new device credential; the old one stays revoked.
Check why a Run is stuck	`hermes-connector recover --list`, then `hermes-connector recover <run_id> --confirm`. A Run interrupted by a restart is never re-executed automatically: at-most-once beats liveness.
See what the Connector decided at start	`journalctl --user -u aamg-hermes-connector` — one line per start, naming anything it recovered.

Troubleshooting

Symptom	Cause and fix
`no Gateway origin is configured` on `connect`	The build carries no release origin. Use `hermes-connector connect --gateway-url https://<your-gateway>` (HTTPS only) — or install the published package, which carries the production origin.
`the release-configured Gateway origin is the staging endpoint`	A staging endpoint is never a valid default. Pass `--gateway-url` explicitly if you really mean staging.
Approval screen says the origins do not match	The App build and the Connector were pointed at different Gateways. Re-run `connect` with the origin this App is configured for.
Pairing link rejected or expired	The five-minute window closed, or the request was already claimed. Start a new `connect`.
`status` exits `2`	This credential is revoked. Re-pair with `connect --re-pair`.
The App says it cannot reach the Gateway	Check the App is on a network that can reach the Gateway origin shown on its pairing screen, then check the Gateway itself: `curl https://<origin>/healthz`.

Where your data lives

The Gateway stores your conversations, runs, events and artifacts so they survive an App restart. Your agent's reasoning, tools, shell commands and model calls stay on your machine: the Gateway never executes them and never pays your token bill. Pairing material is one-time and short-lived, device credentials are stored hashed on the Gateway and in an owner-only file on your machine, and revocation is terminal. See security.md for the full model.

Status of this guide

Written against the shipped package @azuddin/[email protected] and the production Gateway at https://aamg-api.azuddin.com. The Android APK offered on the download page is a sideload beta: signed with a test key rather than a store upload key, because no store identity has been chosen yet. iOS is not distributed at all. When production onboarding changes, this file and the App's Connect Hermes screen change together — both read the same install-command constant.