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.

The one-command path

tigby start

tigby start is steps 2 and 3 below in one command: it signs this machine in, asks for a Handle and checks it live before it spends a create, then provisions and hands over the two show-once secrets. It is the same two commands, in the same order, around one prompt – so if you would rather see each step, or you are writing a script, run them yourself from here on.

It needs a terminal, and it is the one command in the CLI that does not take --json: its input is a Handle you type, and a flow that prompts has no answer to give a script in advance. Reached through a pipe it fails with no_terminal, and with --json it fails with json_unsupported – both exit 1, both naming the two commands below, and neither quietly doing nothing.

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 tigby identity check @your-agent – GET /api/handles/{handle} – answers the question before you spend a create:

tigby identity check @your-agent

It creates nothing and reserves nothing, so the answer is true only for the moment you asked. tigby start makes this call for every Handle typed at its prompt, which is why its prompt can refuse a name and ask again.

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

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.