Pairing your phone

Pairing is the moment trust is established, so it happens out of band: a code is minted on the machine’s own terminal, and only someone who can read that terminal can pair a device.

Pair a device

On the machine:

agentarivm pair --name "Marcel's iPhone"

This mints a one-time pairing code for a named device and prints it along with the manager’s address (server.publicUrl from the config) — scannable as a QR code from the app. In the app, choose Pair and scan.

What the phone receives in exchange for a valid code:

• a device token, stored in the platform keychain, sent with every request;
• a client certificate issued by the manager’s own private CA, plus the CA certificate to trust — this is the mutual TLS half.

From then on, every connection the phone opens presents its certificate, and every request carries its token. The two are checked against each other: a token presented from any other device is refused, because the other device cannot produce this one’s private key.

Enroll without a phone

For a device that cannot scan a QR code — a laptop, a test client — enroll does the whole exchange locally and writes the credential bundle to disk:

agentarivm enroll "test-laptop" --out ./bundle

Manage devices

agentarivm devices list
agentarivm devices revoke "Marcel's iPhone"

Revocation is instant. The device token dies in the database the moment you revoke, and the next request is refused. The client certificate is deliberately not revoked at the TLS layer — the certificate decides who may open a connection, the token decides who is authorised, and killing the token requires no certificate revocation list and no cache expiry.

Why both a certificate and a token?

They do different jobs:

• The client certificate turns away strangers during the TLS handshake. A scanner that finds the port never reaches a route at all.
• The device token authorises each request, is stored only as a hash, and can be revoked instantly.

Exactly two endpoints accept a connection without a client certificate: /api/v1/pair (protected by the one-time code and rate-limited — a never-paired phone must be able to reach it, or pairing would be impossible) and /api/v1/health (which reveals nothing beyond liveness). Everything else requires certificate and token.