Skip to main content
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 — Generate a pairing code

Navigate to your project directory and run the init wizard: 
cd /path/to/your/project
remoteagent init
The wizard asks a few questions:
  • Project name — used to identify this agent in the dashboard and bot messages. Defaults to the directory name.
  • Runner — which AI engine to use. See Runners for the full list. Defaults to claude-sdk.
  • API key — only prompted for runners that require one. Stored locally in ~/.remoteagent/config.json and never transmitted to any server.
At the end of the wizard, the terminal displays a pairing code: 
Your pairing code: XK9-4TZ

Go to https://remoteagent.chat/connect and enter this code.
The code expires in 10 minutes.
The pairing code is single-use and expires after 10 minutes. If it expires before you complete pairing, run remoteagent init again — this generates a new code without overwriting your existing configuration.
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 2 — Open the connect page

On your phone or browser, go to: remoteagent.chat/connect

​
Step 3 — Log in with Telegram

Click the Login with Telegram button. 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 uses the Telegram Login Widget, which is a standard OAuth-style flow run entirely by Telegram. RemoteAgent receives a verified user ID and username — not your password or phone number.

​
Step 4 — Enter the pairing code

Type (or paste) the pairing code from Step 1 into the code input field and click Connect. The page confirms the pairing within a few seconds. Simultaneously, the Telegram bot sends you a confirmation message with a summary of the paired agent (project name, runner, machine hostname).

​
Step 5 — Start the agent

Back in your terminal, start the agent process: 
remoteagent start
The agent connects to its Redis channel and begins listening for commands. You will see a log line like: 
Agent online — listening on channel agent:a1b2c3d4-...
Your bot is now active. Send any message to it in Telegram and the agent will process 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 places on your machine:
  • ~/.remoteagent/config.json — global settings (API key, preferred language)
  • ~/.remoteagent/agents/{agentId}.json — per-agent settings (agent ID, token, project path, runner, Redis URL)
Neither file is ever read by the RemoteAgent servers. The agent token in the per-agent config is a JWT used only to authenticate Realtime channel subscriptions — it does not grant access to your files or API keys.