Skip to main content
Rrelay»

Getting Started

Installation, prerequisites, and first steps with your personal AI agent

Prerequisites

  • Node.js >= 18 (or Bun)
  • OpenCode — the AI backend (npm i -g opencode-ai@latest)
  • A Telegram bot token from @BotFather
  • Your Telegram user ID (get it from @userinfobot)
  • An API key for at least one AI provider (Anthropic, OpenAI, Google, etc. — see Providers)

Installation

npm install -g @4via6/relay

Configuration

Run the interactive setup wizard to create your config at ~/.relay/config.json:

relay onboard

The wizard walks you through 6 steps:

  1. OpenCode — Detects your OpenCode installation (installs if missing)
  2. Bot Token — Telegram bot token from @BotFather
  3. User ID — Your Telegram user ID (only this user can interact with the bot)
  4. Timezone — Select your timezone (affects cron scheduling and timestamps)
  5. MCP Tools — Select built-in tools: Browser (Playwright), Fetch, Memory, Filesystem, GitHub, Context7
  6. Voice — Speech-to-text provider configuration

Provider API keys are set in OpenCode's environment. See Providers for details.

Re-running relay onboard on an existing config enters update mode — shows current values and lets you press Enter to keep them, or type a new value to replace.

Run

Foreground (default)

relay

Background (daemon mode)

Run as a background service that survives terminal closure:

relay start                  # Start as background daemon
relay status                 # Check status (PID, uptime, memory)
relay logs                   # Tail daemon logs (Ctrl+C to exit)
relay restart                # Restart the daemon
relay stop                   # Stop the daemon

pm2 is auto-installed on first relay start. CLI flags are forwarded.

Updating

relay update

Updates to the latest version. Restarts the daemon if it's running.

Open your bot in Telegram and send /start to verify the connection. Use /help to see all available commands.

Data Directory

Relay stores all state in ~/.relay/ (or ./.relay/ in dev mode with --dev flag):

  • config.json — User configuration
  • session.json — Active session ID and selected model
  • cron.json — Scheduled task definitions and run history
  • watch.json — Web monitoring definitions, snapshots, and check history
  • SKILL.md — Custom system prompt (optional, create manually)
  • RELAY.md — Auto-generated assembled system prompt (base + MCP docs)
  • memory.jsonl — Memory MCP knowledge graph data (auto-created when Memory MCP is enabled)

Next Steps