Quickstart

Two minutes is a measured budget, not a slogan: install, sign in, create – then wire the Identity into your agent.

1. Install the CLI

curl -fsSL https://get.tigby.eu | sh

npx tigby runs the same binary without installing anything. Windows, verification and first-run notes: Install the CLI.

2. Sign in

tigby login

The terminal prints a short code; confirm it in a signed-in browser, and Tigby mints a named Admin Key for this machine. No account yet? Create one at tigby.eu/start – an email address and a magic link are the whole signup.

3. Create the Identity

tigby identity create @your-agent

Replace @your-agent with the name you want – run the line as printed and it is refused, on purpose. A Handle is a–z, 0–9 and hyphen, three characters or more, and it is permanent: it is never reissued, not even after a delete. Part of the namespace is reserved – role addresses, infrastructure names, anything containing the brand, and the names these pages print, orderbot and the your-agent placeholder among them – so both tigby identity create @orderbot and the line above are refused with handle_reserved, and a name somebody already holds with handle_taken. Both refusals say which it was, and GET /api/handles/{handle} answers the question before you spend a create.

The command reserves the Handle and runs the provisioning saga – Mailbox, Tunnel, A2A Card, then the first Identity Key – printing each step as it finishes:

mailbox done
tunnel done
card done
identity_key done
Identity @your-agent is ready.
your-agent@tigby.eu · https://tigby.eu/@your-agent
tunnel your-agent.tigbywire.eu · tcp 20047

The Identity Key and the Mailbox password follow, each shown exactly once – store them then.

Two calls stand behind that last line, and it matters if you are driving the API yourself: GET /api/identities/{handle} is the status resource you poll, and it carries no credential in any state, so a harness may repeat it freely. GET /api/identities/{handle}/identity-key is what hands the Identity Key and the Mailbox's IMAP credentials over, and POST /api/identities/{handle}/identity-key/ack says you have them, which is what forgets them. The CLI makes all three for you. If the terminal running tigby identity create does not survive the moment, tigby identity key @your-agent hands them over instead – until the acknowledgement lands or a short window closes. The Identity Key cannot be re-minted afterwards; a fresh one means a fresh Identity, under a new Handle.

4. What now exists

Read this table; do not run it. orderbot is the worked example these pages show, and it is a reserved name – yours carries the Handle you chose in step 3.

5. Wire it into your agent

Give the agent its Identity Key (tigby_id_…) and pick a surface:

• Expose its server: tigby tunnel connect @orderbot --port 3000 – requests to the Tunnel hostname reach the local port. Guide.
• Read and send mail: GET /api/identities/orderbot/messages and POST /api/identities/orderbot/messages/send. Outbound mail needs an Allowed Recipient first.
• Use an SDK: @tigby/sdk on npm, tigby on PyPI.
• Or MCP: tigby mcp runs the tool set over stdio; the same server answers at https://api.tigby.eu/api/mcp.