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

# Architecture

> How RemoteAgent.CHAT works — the message flow from Telegram to your agent and back.

RemoteAgent.CHAT is built on a serverless-first architecture. There is no custom server to maintain on the cloud side, and no persistent connection between Telegram and your machine. Everything is event-driven.

## Components

**RemoteAgent.CHAT cloud** — a serverless web app that handles Telegram webhook events, authenticates requests, and relays messages. It has no persistent state beyond what's in the database.

**Message broker** — a managed pub/sub layer that decouples the cloud from your agent. Messages flow in real time without polling.

**Your agent** — the only persistent process in the system. It runs on your machine, listens for incoming commands, calls your AI runner, and streams output back.

## Message flow

```
You (Telegram)
     │
     ▼
Telegram servers
     │  webhook
     ▼
RemoteAgent.CHAT cloud
  — verifies request authenticity
  — identifies the target agent
  — publishes command to message broker
     │
     ▼
Message broker
     │
     ▼
Your machine (agent process)
  — receives command
  — calls AI runner with the prompt
  — streams output chunks as produced
     │
     ▼
Message broker
     │
     ▼
RemoteAgent.CHAT cloud
  — forwards each chunk to Telegram
     │
     ▼
You (Telegram) — output streams in real time
```

## Design principles

**Your API key never leaves your machine.** The agent calls your AI runner locally. No credentials are transmitted to RemoteAgent.CHAT servers.

**Serverless on the cloud side.** The web app wakes on each incoming event, processes it, and exits. There is no always-on server process to maintain or scale.

**The agent is the only stateful piece.** It maintains a persistent connection to the message broker and manages runner lifecycle. Everything else is stateless.

## Pairing

Pairing links your local agent to your Telegram account. You generate a short-lived code from the dashboard, enter it during `remoteagent init`, and the two sides exchange credentials over an authenticated channel. The code expires after 10 minutes and is single-use.

Once paired, the agent authenticates directly with the message broker using a token tied to your account. The pairing code is never used again.