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.

Security is a first-class concern in RemoteAgent.CHAT’s design. The most important property is also the simplest: your API key never leaves your machine.

​
The relay model

RemoteAgent.CHAT is a pure relay. It routes messages between Telegram and your local agent. It does not:
  • Store your prompts or AI responses (only a 200-character preview for the session list)
  • Read your source code
  • See your AI API keys
  • Execute code on your behalf
Your AI runner calls the model API directly from your machine, using credentials stored only on your machine. The RemoteAgent.CHAT servers relay the prompt you sent via Telegram — they do not process it, interpret it, or log it beyond the preview.
Do not include sensitive secrets in your Telegram commands. While the relay does not log prompts, treat Telegram as you would any messaging app — appropriate for instructions, not for embedding credentials.

​
API key storage

API keys are stored locally in:
  • ~/.remoteagent/config.json — global config
  • ~/.remoteagent/agents/ — per-agent config files
These files are written by remoteagent init and read only by the local agent process. They are never uploaded, synced, or referenced by any network request made by the relay. Recommended file permissions: 
chmod 700 ~/.remoteagent
chmod 600 ~/.remoteagent/config.json
chmod 600 ~/.remoteagent/agents/*.json

​
Agent authentication

When you complete pairing, the server issues a signed token stored in the per-agent config. This token authenticates the agent’s connection to the message broker and scopes it strictly to its own channels — an agent cannot access another agent’s messages or data. Tokens can be revoked by deleting the agent from the dashboard.

​
Telegram webhook verification

Every incoming message from Telegram is verified using a cryptographic signature before any processing occurs. Requests that fail verification are rejected immediately.

​
Telegram user authorization

The bot checks the Telegram user ID of every incoming message against the authorized users for your account. Messages from unauthorized IDs are silently ignored — no error response is sent, which avoids leaking information about which user IDs are registered. This check runs before the command reaches your agent, so unauthorized messages are dropped at the gateway.

​
Pairing code security

Pairing codes are:
  • Short-lived — expire after 10 minutes
  • Single-use — marked as used immediately on first redemption
  • Unpredictable — generated with cryptographically secure randomness
The pairing flow requires Telegram authentication before the code can be redeemed. This binds the agent to a verified Telegram identity, not just anyone who has the code.

​
Channel isolation

Each agent communicates only on its own private channel, derived from its token. An agent cannot read or write to another agent’s channel. Session output channels are similarly scoped and unknown to other users.

​
Payment webhook verification

Billing events are verified against a signing secret before any plan changes are applied. Plan updates are only applied after a verified webhook event — never based on redirect URLs, client-side callbacks, or untrusted inputs.

​
Rate limiting

The message endpoint enforces rate limiting per Telegram user ID. Requests exceeding the limit are rejected. This prevents abuse of the relay by scripts or bots flooding the system with commands.

​
Summary

Security controlImplementation
API key isolationStored locally, never transmitted
Agent authenticationSigned token, scoped per agent
Webhook integrityCryptographic signature on every request
User authorizationTelegram user ID check before every command
Pairing code10-min TTL, single-use, cryptographically random
Channel isolationPrivate channels per agent, token-verified
Payment integritySigned webhook events only
Rate limitingPer user ID, enforced at the gateway