For agents · protocol AI1

Redeeming an invitation

The person at the target machine chose you and handed you an AI1 invitation. These instructions are stable and versioned — the runner prints this page’s address so you can rely on them. Follow them in order.

1. Tell the person what they granted

   Confirm, in plain words, that the invitation is a real login to their account and can read, change, and delete anything that account can. If that isn’t what they intended, stop.

2. One line

   This is the whole flow: it detects your platform, downloads the connector, checks it against a SHA-256 pinned in the script, verifies the Developer ID signature and team on macOS, and redeems the invitation. The steps below are what it does, for when you would rather do them yourself.

   # macOS or Linux — asks for the invitation, echoes nothing
   sh -c "$(curl -fsSL https://agentinvite.app/agent)"
   
   # Windows
   irm https://agentinvite.app/agent.ps1 | iex

   It asks for the invitation rather than taking it on the command line, because a command line is written to ~/.zsh_history or PowerShell’s ConsoleHost_history.txt in plaintext, where a temporary secret outlives the session it belongs to. For automation, set AGENT_INVITE_AI1 instead — the script reads it, then removes it from the environment so nothing it runs inherits it:

   # automation, macOS or Linux
   AGENT_INVITE_AI1='AI1....' sh -c "$(curl -fsSL https://agentinvite.app/agent)"
   
   # automation, Windows
   $env:AGENT_INVITE_AI1='AI1....'; irm https://agentinvite.app/agent.ps1 | iex

   Either way the invitation never becomes an argument: /proc/<pid>/cmdline is world-readable and /proc/<pid>/environ is not, and the connector refuses an AI1. passed as an argument for the same reason. Read it first with curl -fsSL https://agentinvite.app/agent.

3. Get the official connector and verify it

   Download the connector for your own OS and architecture, then check its SHA-256 against the value below before running it. A digest mismatch is a hard stop — never bypass it. The macOS builds are also Developer ID signed, so codesign --verify is a second independent check. The Windows build is not Authenticode signed yet, so the digest is the only check it has — verify it with Get-FileHash and do not skip it.

   # pick one
   curl -fsSLO https://agentinvite.app/agent-access-macos-aarch64
   curl -fsSLO https://agentinvite.app/agent-access-macos-x86_64
   curl -fsSLO https://agentinvite.app/agent-access-linux-x86_64
   curl -fsSLO https://agentinvite.app/agent-access-linux-aarch64
   curl -fsSLO https://agentinvite.app/agent-access-windows-x86_64.exe
   
   # verify, then make it executable
   shasum -a 256 agent-access-*        # or sha256sum on Linux
   chmod +x agent-access-*

   Build	SHA-256
   agent-access-macos-aarch64	edbfd08d2236d160493e22132d1a0fb659c5292b6b1f0372cffa12d92cd4fc1c
   agent-access-macos-x86_64	ff1ffe73d4d3c0bf0e424519ac9d7c10ff07af285c8eec5a526ec799fae9d9f6
   agent-access-linux-x86_64	f096f1da0cec3d8a37fe4c67a4204c4ab40c56b55c8adae62dee3e1f6b5c74e7
   agent-access-linux-aarch64	1b4fa9a1ff68d0918a040168cc54f834e2ac875318c7cc3da4d4a9b07c59d75d
   agent-access-windows-x86_64.exe	907d0f6e1bed36c342c0a219913301bbf9355dc95c140c78aa956ab3ade05acb

4. Submit the invitation over stdin

   Run agent-access invite and paste the invitation at the prompt, or pipe it in. The connector refuses an AI1. value passed as an argument, on purpose.

   # paste at the prompt
   agent-access invite
   
   # or pipe it in, then run a command
   printf '%s\n' "$AI1" | agent-access invite -- your-command

   It then prints the exact connect command for running more commands in that session. Every session gets its own pack file, so use the command that session printed, never one from another session. Each connect first names the account and session it is about to use. If that is not the machine you meant, stop.

   Each argument after -- reaches the machine as one word, so -- 'uname -a; id' looks for a program literally named that. To run several commands on a macOS or Linux machine, pipe a script:

   agent-access connect <pack> -- sh -s < script.sh

5. Redeem, decrypt, and verify — locally

   The connector claims the invitation once, decrypts the connection details on your machine, and pins the target’s host key from the authenticated envelope. The rendezvous never holds the key that decrypts it. A second attempt on a claimed invitation is denied.

6. Connect with forwarding and file transfer off

   The connector launches the standard OpenSSH client with strict host-key checking on and agent, X11, TCP, and stream forwarding disabled. Keep them disabled. Do not weaken security settings to retry.

7. Clean up, and tell them to stop

   On disconnect, expiry, or error, delete the decrypted key material and the connector from your temporary directory. When the work is done, tell the person at the target to press Stop — their machine owns revocation.

What you can and can’t rely on

• Target-owned expiry. The session ends on the target’s clock. When they stop or it expires, the credential stops working — regardless of anything on your side.
• One redemption. An invitation binds to the first valid claim. If you lose your reservation before acknowledging, ask the person to stop and start a fresh session rather than reusing anything.
• No forensic erasure. Deleting your temporary files removes your managed copy; it does not scrub caches, backups, or the chat that carried the invitation. Don’t claim otherwise to the person.
• Preview transport. The tunnel is a no-SLA preview and can drop. If it does, the session cleans up rather than hanging open — reconnecting means a new invitation.

← Back to Agent Invite