Relay

Your personal AI agent — powered by Telegram. Browse the web, schedule tasks, run shell commands, and talk in your language. Powered by OpenCode with 75+ AI providers including Anthropic, OpenAI, Google, DeepSeek, Mistral, and local models.

Features

• 75+ AI providers -- Anthropic, OpenAI, Google, DeepSeek, Mistral, local models, and more via OpenCode
• Text, voice, photo, and file input -- send messages in any format
• Streaming responses -- live-streamed with reasoning display in collapsible blockquotes
• Session management -- create, switch, fork, delete, rename, and list sessions
• MCP tools -- Browser, Fetch, Memory, Filesystem, GitHub, Context7, plus custom servers at runtime
• Scheduled tasks -- cron jobs on a schedule (interval, daily, weekly, once) with isolated sessions
• Shell access -- run commands on your machine directly from Telegram
• Voice transcription -- Groq, Sarvam, OpenAI, or AssemblyAI speech-to-text
• Custom system prompts -- load from SKILL.md, hot-reload on change
• File operations -- list, read, find, search, and browse project files
• Dynamic model selection -- models fetched from provider APIs, always up to date
• Background daemon -- run 24/7 with pm2, auto-restart, and remote updates
• Reply & edit -- reply to bot messages for context, edit sent messages to re-prompt

Quick Start

Prerequisites

• Node.js >= 18
• OpenCode (npm i -g opencode-ai@latest)
• A Telegram bot token from @BotFather

Install

npm install -g @4via6/relay
relay onboard

The setup wizard walks through bot token, user ID, timezone, MCP tools, and voice transcription.

Running

Foreground

relay

Background (daemon)

relay start                  # Start as background daemon
relay status                 # Show PID, uptime, memory
relay logs                   # Tail logs
relay restart                # Restart the daemon
relay stop                   # Stop the daemon
relay update                 # Update to latest version + restart

Development vs Production

Relay persists all state (sessions, cron jobs, watches, uploads, custom prompts) in a single data directory. The location depends on how you launch Relay:

| Mode | How to launch | Data directory | |------|---------------|----------------| | Production (default) | relay, relay start, relay restart | ~/.relay/ | | Development | npm run dev, or any relay command with --dev | ./.relay/ (current directory) | | Custom | Any command with --data-dir <path> | Whatever you specify |

Relay prints the active mode and directory at startup — for example:

  Relay [PROD] data=/home/alice/.relay
  Relay [DEV]  data=/home/alice/projects/Relay/.relay

Important — if you are developing Relay inside a checkout of this repo and also have the production daemon installed globally, make sure you use --dev (or npm run dev, which passes it for you) whenever you intend to hit the repo's .relay/ folder. Running bare relay inside the repo reads and writes your production data. The startup banner tells you which one is active; check it before you send commands.

The same --dev flag works for every subcommand: relay --dev start, relay --dev status, relay --dev onboard, and so on. All of them route to ./.relay/.

For power users, RELAY_DATA_DIR=/some/path in the environment overrides all of the above — useful for containerised deployments.

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Installation, prerequisites, first steps | | Configuration | All config options and CLI flags | | Providers | Detailed setup for each provider | | Commands | Full command reference with examples | | Features | Streaming, file attachments, voice, MCP, models | | Troubleshooting | Common issues and solutions |

License

MIT