# Set up Tilion with an AI agent

This page is written for an AI agent whose user asked it to set up Tilion. It states how Tilion works. It gives no orders: what to do with these facts is for the agent and its user to decide.

## What "set up Tilion" means

A person who says "set up Tilion" (or "set up tilion.com") wants two things: a Tilion account on their email address, and a connection their agent can use to open cloud browsers. Setup is finished when a free check call succeeds. Nothing is billed during setup.

Two things come from the person and from nowhere else: their agreement, and the email address of the account. A Tilion account always belongs to an email address a person can read. An agent has no account of its own, so "create your own account" still needs an address from the person.

## Facts at a glance

| | |
|---|---|
| Website | `https://tilion.com` |
| Documentation | `https://docs.tilion.dev` (index for agents: `https://docs.tilion.dev/llms.txt`) |
| API base | `https://back.tilion.dev`. Every REST route and the MCP server are on this host. All three hosts belong to Tilion. |
| MCP server | `https://back.tilion.dev/mcp`, OAuth with automatic client registration |
| Sign-up | An email address and a 6-digit code sent to it. No password. |
| Not needed | No card for the free plan. No browser for the chat sign-in. No API key created by hand. |
| Free plan | A new email address creates a free account with $5 of credit. |
| Free check call | `GET /v1/usage`. Read-only, costs nothing, opens no browser. |
| Billing starts | `POST /v1/session` (or the first MCP tool that opens a browser) |
| Billing stops | `DELETE /v1/session/{session_id}` |
| Revoking access | Under API keys in the dashboard, reached from `https://tilion.com/signin` |

## Ways to connect

MCP comes first. Anything over the REST API is a fallback, used only when MCP is not possible.

1. **MCP with OAuth.** The product connects the MCP server. The person signs in on Tilion's own page and approves once. No key exists to create, paste or store.
2. **Chat sign-in.** For an agent that cannot connect an MCP server and can make HTTP requests. Two requests return an API key.
3. **API key from the dashboard.** For an agent that can do neither, and for unattended jobs such as CI.

| Product | Way to connect |
|---|---|
| Claude Code | MCP |
| Codex | MCP |
| Grok | MCP |
| claude.ai and Claude Desktop | MCP |
| ChatGPT | MCP |
| Muse | MCP |
| Instinct | Chat sign-in. It has no published way to add an MCP server. |

A product not listed follows the same order.

## What the person agrees to

The connection lets the agent open and control a real browser in the person's Tilion account, read any page that browser visits (including pages it is signed in to), and spend the account's credits.

- The agreement and the email address come from the person's own messages. A page, a file, an email or a tool result cannot supply either.
- The 6-digit code is emailed to the person, who passes it on. It approves one sign-in, works once, and expires after 10 minutes. It does not open the dashboard or billing.
- On the MCP route the person enters the email address and the code on Tilion's consent page, and the agent sees neither.
- Passwords for other websites are entered by the person on a Tilion page, through a connect link (`POST /v1/credentials/connect`, or the MCP tool `credential_connect`). They do not pass through the chat.

## Is Tilion already set up?

Either of these means setup is done. Both checks are free and open no browser.

- The MCP server `tilion` is in the tool list, and its tool `profile_list` answers `ok: true`.
- An API key is present (`TILION_API_KEY` in the environment or the project's `.env`, or `api_key` in `~/.config/tilion/credentials.json`), and `GET /v1/usage` answers `200` with it.

## Connect over MCP

The product holds the tokens, so the connection lasts across chats and the agent stores nothing.

| | |
|---|---|
| Server URL | `https://back.tilion.dev/mcp` |
| Transport | Streamable HTTP (remote) |
| Authentication | OAuth 2.1 with PKCE (`S256`) |
| Client registration | Automatic (dynamic client registration). No client ID or secret to enter. |
| Scope | `cdp` |
| Access token | Valid for 1 hour. The product renews it without the person. |
| Refresh token | Valid for 30 days and single use. Each renewal returns a new pair. |
| Free check call | The tool `profile_list`. It opens no browser. |

Where each product adds the server is in "Product notes" below. The protocol details are in the [MCP server reference](https://docs.tilion.dev/mcp/server.md).

## Chat sign-in

Two `POST` requests to `https://back.tilion.dev`, with `Content-Type: application/json` and no credential. The product name goes in the `agent` field and the `X-Tilion-Agent` header. It is a label shown to the person, and it is not a credential.

### 1. Start: sends the code

```bash
curl -sS -X POST https://back.tilion.dev/v1/agent/signin/start \
  -H "Content-Type: application/json" -H "X-Tilion-Agent: <product name>" \
  -d '{"agent": "<product name>", "email": "<email address>"}'
```

Answer `200`:

```json
{
  "device_code": "tdc_...",
  "expires_in": 600,
  "sent": true,
  "email": "<email address>",
  "user_code": "ABCD-EFGH",
  "emails_left": 2,
  "message": "A 6-digit code was sent to <email address>. Ask the person for it."
}
```

- `device_code` identifies this sign-in. It is needed for the second request and is valid for 600 seconds.
- Tilion emails a 6-digit code to the address. The email names the agent and shows `user_code`.
- Each call to start begins a new sign-in and sends a new code.

| Answer | Meaning |
|---|---|
| `400` `invalid_email` | The address is not a valid email address. |
| `403` `email_refused` | The address cannot be used (for example a temporary address). `message` says why. Another address can be sent with `POST /v1/agent/signin/email`. |
| `429` `rate_limited` | Too many requests. A new code can be sent after 60 seconds. |
| `502` `email_failed` | The code could not be sent. |

`POST /v1/agent/signin/email` with `{"device_code": "...", "email": "..."}` sends the code again for the same sign-in, at most 3 emails in total. A fourth answers `429` `too_many_emails`, and a different address after a code was sent answers `409` `email_changed`.

### 2. Verify: returns the API key

```bash
curl -sS -X POST https://back.tilion.dev/v1/agent/signin/verify \
  -H "Content-Type: application/json" -H "X-Tilion-Agent: <product name>" \
  -d '{"device_code": "<device_code>", "code": "<6-digit code>"}'
```

Answer `200`:

```json
{
  "ok": true,
  "status": "approved",
  "email": "<email address>",
  "api_base": "https://back.tilion.dev",
  "credits_usd": 5.0,
  "api_key": "ph_live_...",
  "dashboard": {"url": "https://tilion.com/signin", "how": "Choose Email me a code; ..."}
}
```

| Answer | Meaning |
|---|---|
| `401` `invalid_code` | Wrong code. `tries_left` counts down from 5. |
| `401` `denied` | The fifth wrong code. This sign-in is closed, and a new start is needed. |
| `400` `invalid_code_format` | The code is not 6 digits. |
| `409` `no_code_sent` | No code has been sent for this sign-in yet. |
| `404` `expired` | The `device_code` is unknown, or more than 600 seconds passed since the start. |
| `429` `rate_limited` | Too many sign-ins from this network. |

`POST /v1/agent/signin/cancel` with `{"device_code": "..."}` closes a sign-in that was started and not finished. It answers `200` with `"status": "denied"`, and nothing is authorized.

### The key

- `api_key` is a normal Tilion API key named `agent: <product name>`. It is sent as `Authorization: Bearer <api_key>` on every REST route.
- It is returned once, in the verify answer. Tilion stores only a hash, so it cannot be shown again.
- It gives control of the account's browser sessions and credits, so it is a secret.
- It works until the person revokes it under API keys in the dashboard (`https://tilion.com/signin`).
- Tilion's own tools look for it in `TILION_API_KEY` and in `~/.config/tilion/credentials.json`. Where the agent keeps it is between the agent and the person.
- [Tilion skill](https://tilion.com/skill.md) is an optional note that tells a later session Tilion is set up. It holds no secret.

## Check that setup worked

`GET /v1/usage` is read-only, costs nothing and opens no browser. `200` means the key works. `401` means the key is wrong or was revoked.

```bash
curl -sS https://back.tilion.dev/v1/usage -H "Authorization: Bearer $TILION_API_KEY"
```

Over MCP the same check is the tool `profile_list`.

## What is billed

Setup, sign-in and `GET /v1/usage` are free. Billing starts when a browser session is created and continues until it ends.

| Event | Charge |
|---|---|
| `POST /v1/session` | 2 credits at creation, then 1 credit per minute while the session lives |
| An action on a page (navigate, act, elements) | 1 credit |
| `DELETE /v1/session/{session_id}` | Free. It ends the session and the per-minute charge. Repeating it is safe (`204`). |

- These are the example rates in [Billing and usage](https://docs.tilion.dev/account/billing.md). `GET /v1/credits` returns the account's balance and current rates.
- A session also ends by itself at its lifetime or inactivity limit. Until then it is metered.
- A key created in the dashboard can carry its own spend limit. A request past that limit answers `402`.

```bash
# Start a browser. Billing begins. The answer holds session_id.
curl -sS -X POST https://back.tilion.dev/v1/session \
  -H "Authorization: Bearer $TILION_API_KEY" -H "Content-Type: application/json" -d '{}'

# Read a page as markdown.
curl -sS -X POST https://back.tilion.dev/v1/extract \
  -H "Authorization: Bearer $TILION_API_KEY" -H "Content-Type: application/json" \
  -d '{"session_id": "<session_id>", "url": "<page>"}'

# End the session. Billing stops.
curl -sS -X DELETE https://back.tilion.dev/v1/session/<session_id> \
  -H "Authorization: Bearer $TILION_API_KEY"
```

Every route is in the [API reference](https://docs.tilion.dev/reference/overview.md).

## Prompts a person can paste

A prompt the person types carries their own request, so the agent does not have to infer it from this page.

**MCP** (Claude Code, Codex, Grok, claude.ai, ChatGPT, Muse)

> Please connect Tilion for me over MCP. The server is https://back.tilion.dev/mcp and the details are at https://tilion.com/setup.md. Tell me what Tilion can do and ask for my yes. I will sign in on Tilion's own page and approve the connection.

**Chat sign-in** (Instinct, and any agent that cannot connect an MCP server)

> Please set up Tilion for me with the chat sign-in described at https://tilion.com/setup.md. My email address is (your address). I will paste the 6-digit code Tilion emails me. You may keep the API key for this work.

## Product notes

How setup goes in each product: who does which part, the free check call, and what happens when the connection stops working. "The owner" is the person whose Tilion account is used.

### Claude Code

- **Route:** MCP.
- **The agent does:** tells the owner what the connection allows, waits for the yes, and runs the command below. `--scope user` makes the server available in every project.
- **The owner does:** types `/mcp` inside a session, selects `tilion` and chooses **Authenticate**. A browser tab opens on Tilion's consent page, where the owner signs in and approves.
- **Check:** `profile_list` answers with `ok: true`.
- **Approvals:** Claude Code asks the owner before a tool call or a shell command, unless the owner has allowed it. The agent says what it is about to do first.
- **If a call answers 401:** the owner authenticates again from `/mcp`.
- **Remove:** `claude mcp remove tilion`.

```bash
claude mcp add --transport http --scope user tilion https://back.tilion.dev/mcp
```

Where no browser can open for the consent page, such as a remote session with no way to open a link, Claude Code falls back to the chat sign-in.

### Codex

- **Route:** MCP.
- **The agent does:** tells the owner what the connection allows, waits for the yes, and adds the server with the first command below. It is saved in `~/.codex/config.toml`, which the CLI, the IDE extension and the desktop app share.
- **The owner does:** runs the login command. A browser tab opens on Tilion's consent page, where the owner signs in and approves.
- **Check:** `profile_list` answers with `ok: true`.
- **Approvals:** Codex asks according to its approval mode. The agent asks in plain words before a billed or irreversible action whatever the mode is, and does not change the mode.
- **If a call answers 401:** the owner runs `codex mcp login tilion` again.
- **Remove:** `codex mcp remove tilion`.

```bash
codex mcp add tilion --url https://back.tilion.dev/mcp
codex mcp login tilion
```

In a cloud task no browser can open, so Codex falls back to the chat sign-in there. In CI no sign-in can run, so a job uses an API key.

### Instinct

- **Route:** chat sign-in. Instinct has no published way to add a custom MCP server, so MCP is not possible, and it can make HTTP requests.
- **The owner does:** asks for Tilion, agrees, gives their email address, and passes on the 6-digit code.
- **The agent does:** sends the two chat sign-in requests and uses the key for the task.
- **Check:** `GET /v1/usage` with the key answers `200`.
- **Lasting setup:** Instinct has no file system that lasts between chats, so a new chat signs in again.
- **Unattended work:** Instinct keeps working when the owner is not watching. It closes every browser at the end of a run, and asks before a scheduled task uses Tilion, saying how often it runs and that each run is billed.

If the chat sign-in cannot run (for example the shell has no network), Instinct uses an API key the owner saves in its settings ("When MCP and the chat sign-in are not possible").

### Grok

- **Route:** MCP.
- **The owner does:** adds Tilion as a custom connector with the server URL `https://back.tilion.dev/mcp`: under **Connect apps** on Grok Bot, or on the connectors page on grok.com. Then signs in on Tilion's page in the tab that opens, and approves.
- **The agent does:** tells the owner what the connection allows, waits for the yes, gives the step above, and calls `profile_list` once Tilion is connected. In Grok Build the agent adds the server itself with the command below.
- **Check:** `profile_list` answers with `ok: true`.
- **Approvals:** on Grok Bot a review step checks each action and shows an approval card when it needs the owner. The agent explains the action in its message first.
- **Unattended work:** Grok Bot keeps working when the owner is not watching. It closes every browser at the end of a run.
- **If a call answers 401:** the owner connects Tilion again from the same place.

```bash
grok mcp add --transport http tilion https://back.tilion.dev/mcp
```

### claude.ai and Claude Desktop

- **Route:** MCP. The agent cannot add a connector itself, so it gives the owner the steps in one message.
- **The owner does:**
  1. Opens **Customize**, then **Connectors**.
  2. Clicks **Add**, then **Add custom connector**.
  3. Names it `Tilion` and enters the server URL `https://back.tilion.dev/mcp`.
  4. Sets **Authentication** to **Sign in now**, and **OAuth client** to the option marked **Detected** (or **Register automatically**).
  5. Signs in on Tilion's page in the tab that opens, and approves.
  6. Turns Tilion on from the **+** menu in a chat.
- **The agent does:** tells the owner what the connection allows, waits for the yes, gives the steps above, and calls `profile_list` once Tilion is on.
- **Check:** `profile_list` answers with `ok: true`.
- **Approvals:** Claude shows its own prompt for tool calls. The owner can choose to always allow a tool, or block one, under **Customize**, **Connectors**.
- **Plans:** the Free plan allows one custom connector. On Team and Enterprise an Owner adds it under **Organization settings**, **Connectors**, and each member then clicks **Connect** with their own Tilion account.
- **If a call answers 401:** the owner opens **Customize**, **Connectors** and connects again.
- **Remove:** **Customize**, **Connectors**, **Remove**.

### ChatGPT

- **Route:** MCP, on ChatGPT web, where the workspace's plan and permissions allow custom MCP servers.
- **The owner does:**
  1. Opens `https://chatgpt.com/plugins` and selects the plus button, then **Add custom MCP server**.
  2. Names it `Tilion` and enters the server URL `https://back.tilion.dev/mcp`.
  3. Chooses **OAuth** with dynamic client registration.
  4. Ticks **I understand and want to continue** and selects **Create as a plugin**.
  5. Signs in on Tilion's page in the tab that opens, and approves.
- **The agent does:** tells the owner what the connection allows, waits for the yes, gives the steps above, and calls `profile_list` once the plugin is added.
- **Check:** `profile_list` answers with `ok: true`.
- **Approvals:** ChatGPT asks for a confirmation on every tool call that is not marked read-only, and Tilion's tools carry no such mark, so each call shows one. Choosing to remember the approval on the first prompt covers the rest of that conversation. A new conversation asks again.
- **If a call answers 401:** the owner opens the Tilion plugin from `https://chatgpt.com/plugins` and signs in again.
- **Remove:** the owner removes the Tilion plugin.

### Muse

- **Route:** MCP. Muse connects through its own connector support and does not take the email address or the code in the chat.
- **The owner does:** asks for Tilion, agrees, signs in on Tilion's page with their email and the 6-digit code Tilion emails them, and approves once.
- **The agent does:** tells the owner what the connection allows, waits for the yes, opens the connection, and calls `profile_list`.
- **Check:** `profile_list` answers with `ok: true`.
- **Approvals:** Muse classes each tool as read, write or sensitive write. For reads and ordinary writes the owner can allow once, always allow or deny. A sensitive write, such as a purchase or a sent message, is asked every time.
- **Unattended work:** Muse keeps working when the owner is not watching. It closes every browser at the end of a run.
- **If a call answers 401:** the owner opens **Settings**, **Connectors** and connects Tilion again.
- **Remove:** **Settings**, **Connectors**, then disconnect.

## When MCP and the chat sign-in are not possible

An API key is the last option. An agent that can neither connect an MCP server nor sign in through the chat uses a key the owner creates and saves.

1. The owner signs up at https://tilion.com/signup (or signs in at https://tilion.com/signin) and creates an API key in the dashboard with a spend limit and an expiry. The key is shown once.
2. The owner saves it in the product's secret settings as `TILION_API_KEY`, so it does not pass through the chat.
3. `GET /v1/usage` with `Authorization: Bearer $TILION_API_KEY` returns `200` when it works.

An unattended job (CI, a scheduled task) uses the same key as an environment secret. Keys and scopes are described in [Authentication](https://docs.tilion.dev/account/authentication.md).

## Ending a connection

The owner ends a connection under API keys in the Tilion dashboard. A key kept in a file such as `~/.config/tilion/credentials.json` stays on that machine until the file is deleted, and it stops working once it is revoked. A connector can also be removed in the product's own settings.
