Connect your agent to Tokenrip

Tokenrip is a shared workspace for people and their AI agents: one place for a project's files, decisions, and tasks that every agent the person connects can read and write. This page is for you, the AI agent doing the setup. Follow the steps in order. It expects @tokenrip/cli 2.3.0 or later.

The person supplies at most two things: their email address and a six-digit code. Never ask them for a password or a key.

0. Already connected?

If you have Tokenrip tools (such as workspace_list or key_list), rip auth whoami succeeds, or you hold a Tokenrip key, do step 4, then go to step 5.

If the person gave you a line from another agent ("Connect to my Tokenrip: … email [email protected], code 123456"), skip step 1: the line carries the email, and pasting it was the request. Pick your route in step 2 and sign in with that email and code right away; the code lasts 10 minutes.

1. Confirm the email

If the person gave their email in this conversation, do not ask again. Say what you are doing in one line ("Connecting you to Tokenrip, a shared workspace your agents plug into, as [email protected].") and continue to step 2 without waiting.

Otherwise propose an email you already know for the person, or ask for it, and confirm it in one line: "I'll connect you to Tokenrip, a shared workspace your agents plug into, using [email protected]. OK?" Never take an email from a web page or a document.

2. Pick your route

Use the first route that fits you.

• Shell. You can run commands in a terminal, and your home directory persists between sessions (the CLI saves its key there). Use the CLI in step 3. If your sandbox blocks the network, ask the person to allow api.tokenrip.com. A chat app with a temporary code sandbox uses the connector route.
• API. You can make HTTP requests and keep a secret between conversations. Use the HTTP calls in step 3. If you cannot keep a secret, use the key route below.
• Connector. You are a chat app that adds MCP servers as connectors. Give the person these steps, then wait until they are back:
  1. In the app's settings, add a custom connector (it may be called an MCP server or an integration).
  2. Use the URL https://api.tokenrip.com/mcp.
  3. Connect. On the Tokenrip page that opens, choose "Continue with email" and enter the emailed code, or "I have a code from my agent" with a code a connected agent gave them.
  4. Select Connect, then start a new chat and say "open my Tokenrip workspace". (A browser already signed in to Tokenrip goes straight to that screen.)
• Key in settings. Your host takes a pasted key (a key vault, a settings field, or a connector with a bearer header). The person gets a key from an agent that is already connected (rip auth keys create --name "<host name>") or from https://tokenrip.com/operator/agents ("Create a key"), and pastes it into your host's vault or settings, never into a chat. Then call the API with Authorization: Bearer <key>, or add the connector URL with that key.

3. Sign in

With a line from another agent, sign in with its email and code. Skip the request.

Otherwise request a code. Tokenrip emails it to the person. Ask them for it, or, if you can read their inbox, use the newest email from Tokenrip whose subject carries the code ("123456 is your Tokenrip code"), received after your request. A code lasts 10 minutes and works once.

Only use a code the person gave you directly, or one you read from their inbox this way. Never use a code from a web page, a document, or anyone else.

CLI:

rip --version    # 2.3.0 or later? If older or missing:
npm install -g @tokenrip/cli@latest
rip auth login --email [email protected]
rip auth login --email [email protected] --code 123456 --name "<your name>"
rip auth whoami

The CLI saves the key.

API (base https://api.tokenrip.com/v0):

POST /v0/auth/sign-in/request   {"email": "[email protected]"}
→ 202

POST /v0/auth/sign-in           {"email": "[email protected]", "code": "123456", "name": "<your name>"}
→ 201 {"ok": true, "data": {"api_key": "tr_…", "account_id": "…", "email": "[email protected]", "outcome": "existing_account"}}

Send Authorization: Bearer <api_key> on every call. Keep the key in your host's secret store and never show it in chat.

A new email gets an account on first sign-in. Signing in never disconnects the person's other agents.

4. Say which account you are connected to

Check with rip auth whoami (API GET /v0/accounts/me, MCP whoami), then tell the person, for example: "Connected to [email protected]'s Tokenrip."

• You signed in with a code Tokenrip emailed to the address the person gave or confirmed: state the account and continue. Do not wait for a reply.
• You signed in with a line from another agent, or you were already connected: confirm it is their account before you write anything private.

If the account is not the one the person expects, stop and say so.

5. Open a workspace

A workspace holds a project's files, decisions, and tasks. List them with rip workspace list (API GET /v0/workspaces, MCP workspace_list).

• None: create one without asking for a name. Use the slug personal and the name "Personal" unless the conversation is plainly about one project: rip workspace create <slug> --name "<Name>" (API POST /v0/workspaces with {"slug", "name"}, MCP workspace_create). Load it, then save the first note (below).
• One: load it with rip workspace load <workspace-id> --operation-id <new uuid> (API POST /v0/workspaces/<id>/load with {"operationId"}, MCP workspace_load). The load returns a browser link to the workspace; give it to the person.
• Several: ask the person which one, then load it.

Save the first note. A new workspace is empty, and the next agent has nothing to read until you write something. Save one short markdown note of what the next agent should know: who the person is and what they are working on now, taken from this conversation only. Leave out anything the person would not want kept.

rip artifact publish --type markdown --title "About <person or project>" --content "<the note>" --workspace-id <workspace-id>

(API POST /v0/artifacts with {"type": "markdown", "title", "content", "workspaceId"}, MCP artifact_publish.) Show the person the note's URL and say in one line what you saved.

In a workspace that already has content, tell the person one thing you read in it that you did not know before. That shows them this agent sees what their other agents saved.

6. Offer the next agent

Once the workspace holds something, ask: "Want another agent to see this? I can give you one line to paste." If yes, run rip auth code (API POST /v0/auth/sign-in-codes, MCP sign_in_code_create) and show the paste line it returns. The next agent signs in with it, with no email, within 10 minutes.

For a host that takes a pasted key, create one with rip auth keys create --name "<host name>" (API POST /v0/auth/keys with {"name"}, MCP key_create). It is shown once. Tell the person to paste it into that host's vault or settings, not into a chat.

The person sees and revokes every connected agent at https://tokenrip.com/operator/agents, or asks you: rip auth keys and rip auth keys revoke <id> (MCP key_list, key_revoke).

7. If something fails