Configuration

All configuration is stored in ~/.relay/config.json. Run relay onboard to create it interactively, or edit the file directly.

Config resolution order: CLI flags > config file > defaults.

Subcommands

Required Fields

• botToken — Telegram bot token from @BotFather
• allowedUserId — Your Telegram user ID (only this user can interact with the bot)
• provider — "opencode" (the only supported value)

Provider Configuration

Each provider has its own config fields. See Providers for detailed setup.

OpenCode

• opencodeMode — start (default) spawns a local server, connect uses a remote URL
• opencodeUrl — Server URL when using connect mode (default: http://localhost:4096)
• opencodeHostname — Bind address when using start mode (default: 127.0.0.1)
• opencodePort — Port number when using start mode (default: 4096)
• opencodeModel — Model override, e.g. anthropic/claude-sonnet-4-20250514

Provider API keys are configured in OpenCode's environment, not in Relay. See Providers for details.

Timezone

• timezone — IANA timezone string (default: "UTC")

Set during relay onboard (Step 4) or change at runtime with /timezone America/New_York. Affects cron job scheduling, next run times, and the timestamp in the system prompt.

MCP Tools

Built-in MCP tools are configured during relay onboard or directly in the config file:

• browserEnabled — Enable headless browser via Playwright MCP (default: false)
• fetchEnabled — Enable web page fetching as markdown via Fetch MCP (default: false, requires uvx)
• memoryEnabled — Enable persistent knowledge graph across sessions (default: false)
• filesystemEnabled — Enable read/write access to files outside the project (default: false)
• filesystemPaths — Allowed directories for Filesystem MCP (default: [])
• githubEnabled — Enable GitHub API access via GitHub MCP (default: false)
• githubToken — GitHub Personal Access Token for GitHub MCP
• context7Enabled — Enable library documentation lookup via Context7 MCP (default: false)
• context7ApiKey — Optional API key for Context7

When enabled, Relay auto-injects the corresponding MCP server configs into OpenCode's configuration. The Relay MCP (cron, notifications, health) is always enabled automatically.

You can also add custom MCP servers via /mcp add commands. See Commands for details.

Bot Mode

• botMode — polling (default) or webhook
• webhookUrl — Public URL for receiving updates (required for webhook)
• webhookPort — Port for the webhook HTTP server (default: 39148)
• webhookSecret — Optional secret for webhook verification

Long Polling (default)

Connects to Telegram and pulls updates. Works behind NATs and firewalls.

"botMode": "polling"

Webhook Mode

Runs an HTTP server; Telegram pushes updates to it. Lower latency, better for production.

"botMode": "webhook",
"webhookUrl": "https://your-server.com/bot",
"webhookPort": 39148,
"webhookSecret": "your-random-secret"

Requires a public HTTPS URL that Telegram can reach.

Data Persistence

• dataDir — Directory for persisted bot state (default: ~/.relay/, or ./.relay/ with --dev flag)

Relay persists session state, model selection, and provider data to disk so they survive restarts:

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

Streaming

• streamEditIntervalMs — How often in ms to update the Telegram message while streaming (default: 2000)

Streaming is always enabled. Responses are progressively edited in Telegram as the AI generates text.

Timeout

• promptTimeoutMs — Max time in ms to wait for a provider response (default: 300000, 5 minutes)

System Prompt

• systemPromptFile — Path to your custom system prompt file (default: SKILL.md)

Resolved relative to dataDir, so the default location is ~/.relay/SKILL.md. If the file exists, it's loaded as the system prompt; otherwise a built-in default is used. The file is watched and reloaded automatically on change. See Features for details.

Voice / Speech-to-Text

• sttProvider — STT provider: groq, sarvam, sarvam-translate, openai, assemblyai, or auto (default: auto)
• groqApiKey — Groq API key for Whisper
• groqSttModel — Groq transcription model (default: whisper-large-v3-turbo)
• sarvamApiKey — Sarvam AI API key (supports Indian languages)
• sarvamSttModel — Sarvam transcription model (default: saaras:v3)
• openaiSttApiKey — OpenAI API key for speech-to-text
• openaiSttModel — OpenAI transcription model (default: gpt-4o-mini-transcribe)
• assemblyaiApiKey — AssemblyAI API key

Set at least one API key to enable voice support. When auto, the cheapest configured provider is auto-selected. If it fails, other configured providers are tried automatically.

Use sarvam-translate to transcribe and translate non-English voice messages to English. See Providers for details.

Example config.json

{
  "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
  "allowedUserId": "987654321",
  "provider": "opencode",
  "opencodeMode": "start",
  "botMode": "polling",
  "timezone": "America/New_York",
  "browserEnabled": true,
  "memoryEnabled": true,
  "githubEnabled": true,
  "githubToken": "ghp_...",
  "context7Enabled": true,
  "streamEditIntervalMs": 2000,
  "promptTimeoutMs": 300000,
  "groqApiKey": "gsk_..."
}