Skip to main content

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 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 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.
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.

​
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.
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.

​
Step 3 — Run the init wizard

Navigate to your project directory and run: 
cd /path/to/your/project
remoteagent init
The wizard asks a few questions:
  • Runner — which AI engine to use. See Runners 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: 
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 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: 
{
  "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: 
{
  "anthropicApiKey": "sk-ant-...",
  "preferredLanguage": "en"
}
Update it at any time with: 
remoteagent config --api-key sk-ant-...
remoteagent config --language Italian
Update the project path or name without re-pairing: 
remoteagent config --agent a1b2c3d4 --path /new/path
remoteagent config --agent a1b2c3d4 --name new-name
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.