The pairing code
Updated October 28, 2026
How a 6-character code connects an agent to a member's room without anyone, Terebyte included, being able to swap in another key.
In short
- The agent's program shows a 6-character code, such as
4K7QXM. It works for 10 minutes, once. - The member types it in Terebyte (Rooms → Connect an agent), checks who is asking, and approves.
- A server in the middle, ours included, can't put its own key in place of the agent's.
- The agent ends up with a door: a sealed copy of one room's key that only its own private key can open. It never sees the member's vault key, password or recovery key.
The code
- Six characters from Crockford's base 32: the digits and the letters except I, L, O and U.
- When typing it, case, spaces and dashes don't matter, and O counts as 0, I and L as 1.
Expiry and reuse
| How long a code works | 10 minutes from when the program asked for it |
| How often it can be used | Once. A second answer gets "That code has already been used." |
| After Connect | The member's screen waits about five minutes for the agent's answer, then asks for a new code |
| Old pairings | Deleted from our database every hour once past their time |
If the code runs out, the program stops with "The code wasn’t used in time. Run this again for a new one."
What the agent holds
One file, ~/.terebyte/agent.json (or $TEREBYTE_HOME/agent.json). Its folder is readable by that computer's user alone (700) and the file too (600). It holds:
- the server's address, the agent's name and the computer's name;
- the agent's private keys (signing, sealing, post-quantum);
- a list of doors: door id, room id, and the room's name as the member gave it.
It doesn't hold the vault key, a password, an access token, or any room key.
Keep this file safe. Whoever has it can use the agent's doors until they expire, are paused, or are revoked. The JavaScript and Python kits share the same file: pair once, use either.
How the agent proves it holds a door
Every request through a door is signed with the agent's signing key, in the Authorization header:
Authorization: Door <door id>.<time in ms>.<signature>Our server refuses a request more than five minutes from its clock, or from a door that is expired, paused, revoked, or under "Pause all agents", always with the same answer: "This door can’t be used."
How long a door lasts
The member picks it on the approval screen:
| Length | Ends |
|---|---|
| 1 hour | An hour after Approve |
| Today | At 23:59:59 on the member's own clock |
| 30 days | 30 days after Approve |
| Until closed | When the member revokes it |
To keep working after a door ends, pair again.
Good to know
- A sandbox that can't show a code can't be paired: the agent's program must be able to print the code for you.
- A door's permissions and length can't be changed from the app after Approve. Revoke it and pair again.