opencode-gateway

Gateway plugin for OpenCode.

Highlights

The packaged gateway combines the native launcher and the OpenCode plugin into a single local runtime with durable state, channel delivery, scheduling, and memory support.

After initialization and startup, routine gateway use is meant to happen through natural-language conversation with OpenCode rather than through a long list of memorized commands. The CLI exists mainly for bootstrap, diagnostics, and process lifecycle; normal operation is exposed as conversational tools.

Current feature set, grouped by responsibility:

• Lifecycle and workspace management: managed serve; immediate warm-up of the plugin worker; managed restart via gateway_restart; and a workspace scaffold with USER.md, RULES.md, daily notes, workspace-local skills, and the built-in markdown-agents guide.
• Durable execution and routing: SQLite-backed session bindings and runtime journal; durable mailbox workers; per-mailbox serialization; optional batching; shared mailbox routes; and inflight policies with ask, queue, and interrupt.
• Telegram runtime: allowlisted long polling; editable stream previews for private chats; Preview / Tools views with paginated tool history; compaction reactions; file sending; and automatic cleanup for permission/question prompts.
• Scheduling and automation: recurring cron jobs plus one-shot schedules; persisted run history; and operational tools for scheduling, inspection, and manual dispatch.
• Memory and agent operations: workspace-aware memory injection; memory_search and memory_get; agent_status and agent_switch; and channel_new_session for starting a fresh route session.

Operational Note

The packaged gateway is now suitable for regular day-to-day use. Upgrades can still occasionally leave behind stale state or plugin cache artifacts, so keep these cleanup steps in mind when an installed package stops behaving correctly:

• remove the gateway state database at ~/.local/share/opencode-gateway/state.db
• remove the OpenCode plugin cache at ~/.cache/opencode/node_modules/opencode-gateway

After that, run bunx opencode-gateway@latest init again if needed, then start the gateway normally.

Quick Start

Recommended user-facing commands use bunx with the latest version:

bunx opencode-gateway@latest <command>

If you prefer npm, replace bunx with:

npx opencode-gateway@latest <command>

Initialize your OpenCode config:

bunx opencode-gateway@latest init

This ensures:

• plugin contains opencode-gateway@latest
• opencode-gateway.toml exists next to the preferred OpenCode config file

By default the CLI uses OPENCODE_CONFIG_DIR when it is set, otherwise it writes to:

• an existing ~/.config/opencode/opencode.jsonc or ~/.config/opencode/opencode.json
• otherwise a new ~/.config/opencode/opencode.jsonc
• ~/.config/opencode/opencode-gateway.toml

Check what it resolved:

bunx opencode-gateway@latest doctor

Recommended:

bunx opencode-gateway@latest serve

This wraps opencode serve and warms the gateway plugin worker immediately, so Telegram polling and scheduled jobs do not stay idle until the first project-scoped request. In managed gateway sessions, the plugin can also use gateway_restart to request an OpenCode restart on the user's behalf when new skills, agents, or config changes need to take effect.

Once it is running, the normal operator workflow is conversational: ask for a restart, inspect schedules, switch agents, search memory, or start a fresh route session in natural language and let the gateway tools carry out the underlying actions.

If you still prefer the raw OpenCode command, warm the gateway explicitly after startup:

opencode serve
bunx opencode-gateway@latest warm

If you want a separate managed config tree instead of editing your existing OpenCode config:

bunx opencode-gateway@latest init --managed
bunx opencode-gateway@latest serve --managed

Example gateway config

[gateway]
state_db = "/home/you/.local/share/opencode-gateway/state.db"
# log_level = "warn"
#
# Gateway-owned external HTTP requests use HTTP_PROXY, HTTPS_PROXY, and
# NO_PROXY by default. Disable this if your environment proxy should not affect
# Telegram polling, delivery, and file downloads.
# [gateway.http_proxy]
# enabled = true

# Optional mailbox batching and route overrides.
# [gateway.mailbox]
# batch_replies = false
# batch_window_ms = 1500
#
# [[gateway.mailbox.routes]]
# channel = "telegram"
# target = "6212645712"
# topic = "12345"
# mailbox_key = "shared:telegram:dev"
#
# Optional execution timeouts. Defaults are long-task friendly:
# [gateway.execution]
# session_wait_timeout_ms = 1800000
# prompt_progress_timeout_ms = 1800000
# hard_timeout_ms = 7200000
# abort_settle_timeout_ms = 5000
#
# Optional policy for new inbound messages that arrive while the current
# mailbox run is still executing:
# [gateway.inflight_messages]
# default_policy = "ask" # "ask" | "queue" | "interrupt"

[cron]
enabled = true
tick_seconds = 5
max_concurrent_runs = 1

[channels.telegram]
enabled = false
# Ask @BotFather for the bot token. Choose exactly one credential source.
# bot_token = "123456:ABCDEF"
# Or load it from an environment variable:
bot_token_env = "TELEGRAM_BOT_TOKEN"
poll_timeout_seconds = 25
# Configure at least one allowlist when Telegram is enabled.
# Ask @userinfobot for your numeric Telegram user id for private-chat allowlists.
allowed_chats = []
allowed_users = []

[channels.telegram.ux]
# Control Telegram tool-call previews: "toggle", "inline", or "off".
# "toggle" keeps one preview message with Preview / Tools buttons.
tool_call_view = "toggle"
# Add a reaction after OpenCode compacts the session context.
compaction_reaction = true
compaction_reaction_emoji = "🗜️"

[[memory.entries]]
path = "USER.md"
description = "Persistent user profile and preference memory. Keep this file accurate and concise. Record stable preferences, communication style, workflow habits, project conventions, tool constraints, review expectations, and other recurring facts that should shape future assistance. Update it proactively when you learn something durable about the user. Do not store one-off task details or transient context here."
inject_content = true

[[memory.entries]]
path = "RULES.md"
description = "Behavior rules and standing operating constraints for the assistant. Keep this file concise, explicit, and current. Use it for durable expectations about behavior, review standards, output style, safety boundaries, and other rules that should consistently shape future responses. Update it proactively when new long-lived rules or boundaries become clear."
inject_content = true

[[memory.entries]]
path = "memory/daily"
description = "Daily notes stored as YYYY-MM-DD.md files. Use this directory for dated logs, short-lived findings, and day-specific working context that should remain searchable without being auto-injected. Create or update the current day's file proactively when meaningful new day-specific context appears."
search_only = true

[[memory.entries]]
path = "memory/project.md"
description = "Project conventions and long-lived context"
inject_content = true
header = "<important>"
footer = "</important>"

[[memory.entries]]
path = "memory/notes"
description = "Domain notes and operating docs"
search_only = true
header = "<reference>"
footer = "</reference>"

[[memory.entries]]
path = "memory/snippets"
description = "Selected files are auto-injected; the rest stay searchable on demand"
globs = ["**/*.md", "notes/**/*.txt"]

[gateway.execution] is optional. By default the gateway allows long-running OpenCode tasks and only times out stalled waits: session_wait_timeout_ms and prompt_progress_timeout_ms default to 30 minutes, hard_timeout_ms is disabled, and abort_settle_timeout_ms defaults to 5 seconds.

[gateway.inflight_messages] is also optional. default_policy defaults to "ask":

• ask holds new inbound messages while the current mailbox run is still active and sends a local Queue Next / Interrupt Current interaction
• queue keeps the current run and automatically releases the held messages once that run finishes
• interrupt aborts the current run immediately and starts the held messages in the next run

[gateway.http_proxy] is optional and defaults to enabled = true. When enabled, gateway-owned external HTTP requests read http_proxy / HTTP_PROXY, https_proxy / HTTPS_PROXY, and no_proxy / NO_PROXY. Proxy URLs should stay in environment variables rather than the gateway config so credentials are not persisted in TOML. Local OpenCode warm-up and control requests continue to connect directly to the loopback OpenCode server.

Telegram UX defaults:

• private Telegram chats use one editable stream message instead of draft transport
• successful permission and question prompts are auto-removed shortly after reply
• tool_call_view = "toggle" uses one preview message with Preview / Tools buttons instead of mixing tool details into the main preview body
• the Preview view keeps reasoning, process, and the final answer visible; the Tools view paginates tool details newest-first
• when the task finishes, the message returns to Preview, but Tools stays available for later inspection
• the first tool event opens the preview stream immediately so pending/running tool input shows up early
• after OpenCode emits session.compacted, the current Telegram message gets a 🗜️ reaction by default
• when a new inbound message lands during an active mailbox run, Telegram can ask whether to queue it or interrupt the current run, depending on gateway.inflight_messages.default_policy

When Telegram is enabled, either set channels.telegram.bot_token directly or export the token through the configured environment variable, for example:

export TELEGRAM_BOT_TOKEN="..."

Gateway plugin logs are off by default. Set gateway.log_level to error, warn, info, or debug to emit that level and anything above it.

Mailbox rules:

• gateway.mailbox.batch_replies defaults to false
• gateway.mailbox.batch_window_ms defaults to 1500
• gateway.mailbox.routes lets multiple ingress targets share one logical mailbox/session
• each route needs channel, target, optional topic, and a mailbox_key

Memory rules:

• all entries inject their configured path and description
• entry-specific maintenance guidance for USER.md, RULES.md, and memory/daily is injected only when those exact entries are configured
• file contents are auto-injected only when inject_content = true
• search_only = true keeps an entry available to memory_search and memory_get without auto-injecting its content
• directory entries default to description-only plus on-demand search
• directory globs are relative to the configured directory and define which files are auto-injected; other UTF-8 text files remain searchable on demand
• relative paths are resolved from opencode-gateway-workspace
• absolute paths are still allowed
• missing files and directories are created automatically on load
• the default workspace scaffold includes USER.md, RULES.md, memory/daily/README.md, .opencode/skills/README.md, and the built-in .opencode/skills/markdown-agents/ guide
• the default template includes USER.md, RULES.md, and memory/daily
• gateway-managed sessions default to workspace-local skills under opencode-gateway-workspace/.opencode/skills
• globally configured OpenCode skills remain readable, but new or updated gateway skills should default to the workspace-local skills directory unless the user explicitly asks otherwise
• memory is injected only into gateway-managed sessions
• memory_search returns matching snippets and paths; memory_get reads a specific configured memory file by path and optional line window