> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remoteagent.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Pairing

> Link your local agent to your Telegram account using a one-time pairing code.

Pairing is the process of linking a local agent instance (running on your machine) to your Telegram account. Once paired, the bot knows which agent to forward your messages to, and which Telegram user is authorized to send commands.

## Step 1 — Log in to the dashboard

Go to [remoteagent.chat](https://remoteagent.chat) and click **Login with Telegram**.

A Telegram widget will open. Authenticate with your Telegram account — this is the account the bot will accept commands from.

<Note>
  You only need to log in once per browser session. RemoteAgent.CHAT uses the
  Telegram Login Widget, which is a standard OAuth-style flow run entirely by
  Telegram. RemoteAgent.CHAT receives a verified user ID and username — not your
  password or phone number.
</Note>

## Step 2 — Generate a pairing code

In the dashboard, click **Pair new agent** and enter a project name. The dashboard will generate and display a **pairing code**:

```
Your pairing code: XK9-4TZ
Expires in 10 minutes.
```

<Warning>
  The pairing code is **single-use** and expires after **10 minutes**. If it
  expires before you complete pairing, click **Pair new agent** again to
  generate a new one.
</Warning>

## Step 3 — Run the init wizard

Navigate to your project directory and run:

```bash theme={null}
cd /path/to/your/project
remoteagent init
```

The wizard asks a few questions:

* **Runner** — which AI engine to use. See [Runners](/runners/overview) for the full list. Defaults to `claude-code`.
* **API key** — only prompted for runners that require one. Stored locally in `~/.remoteagent/config.json` and never transmitted to any server.
* **Pairing code** — paste the code from the dashboard.

Once the code is accepted, the agent is linked to your Telegram account and starts automatically.

You can also pass flags to skip the interactive prompts:

```bash theme={null}
remoteagent init --runner claude-sdk
remoteagent init --runner custom --runner-bin /usr/local/bin/my-ai-tool
```

## Step 4 — Send your first command

Your bot is now active. Open Telegram, find the **RemoteAgent.CHAT bot**, and send any message to test it.

## Pairing multiple projects

You can pair as many agents as your plan allows by repeating this process in different project directories. Each `remoteagent init` creates a separate agent with a unique ID. See [Multi-project](/bot/multi-project) for details on how the bot handles routing between agents.

## Re-pairing an existing agent

If you need to re-pair an agent (for example, after switching Telegram accounts), run `remoteagent init` again in the same directory. The wizard detects the existing configuration and asks whether to update it or create a new agent.

## Where configuration is stored

After pairing, the agent's credentials are stored in two files on your machine:

### Per-agent config — `~/.remoteagent/agents/{agentId}.json`

One file per paired agent. This is where all agent-specific settings live, including the API key for runners that require one:

```json theme={null}
{
  "agentId": "a1b2c3d4-...",
  "agentToken": "...",
  "projectPath": "/home/you/my-project",
  "projectName": "my-project",
  "runner": "claude-sdk",
  "anthropicApiKey": "sk-ant-..."
}
```

This means each project can use a **different API key** — useful if you have projects billed to separate Anthropic accounts.

### Global config — `~/.remoteagent/config.json`

Shared across all agents on the machine. Only used as a fallback for `anthropicApiKey` if the per-agent file does not define one:

```json theme={null}
{
  "anthropicApiKey": "sk-ant-...",
  "preferredLanguage": "en"
}
```

Update it at any time with:

```bash theme={null}
remoteagent config --api-key sk-ant-...
remoteagent config --language Italian
```

Update the project path or name without re-pairing:

```bash theme={null}
remoteagent config --agent a1b2c3d4 --path /new/path
remoteagent config --agent a1b2c3d4 --name new-name
```

<Note>
  Neither file is ever read by the RemoteAgent.CHAT servers. The `agentToken` is a
  signed credential used only to authenticate the relay — it does not grant
  access to your files, source code, or API keys.
</Note>