opencode-talk-bridge

Drive a local OpenCode coding agent from Nextcloud Talk — a self-hosted chat bridge.

An incoming Talk message is forwarded to a locally-running opencode serve HTTP API; the agent's reply (long output / code as a file attachment) is posted back into the conversation. The bridge uses polling (no webhooks), so it works on institutional Talk instances where you have no admin access and cannot register a webhook bot.

⚠️ This bridge runs AI coding-agent actions on your machine, triggered from chat in infrastructure you may not control. Read the Threat model first. A non-empty user allowlist is mandatory — the bridge refuses to start without one.

How it works

Nextcloud Talk  ──long-poll──▶  bridge  ──HTTP──▶  opencode serve (localhost)
   (you type)   ◀──post────────  bridge  ◀──SSE────  (agent runs locally)

• Polling, not webhooks: the bridge long-polls the Talk chat endpoint (lookIntoFuture=1 + lastKnownMessageId) using only your app password.
• OpenCode stays local: the bridge talks to opencode serve over 127.0.0.1. It does not start OpenCode — run it yourself, via launchd, or via the companion menubar app. The bridge health-checks it and reports when it is down.
• Prompts block; permissions are concurrent: POST /session/{id}/message blocks until the turn finishes, so each prompt runs in a worker thread while a shared SSE consumer (/global/event) routes permission requests back into the conversation in real time.

Requirements

• Python ≥ 3.10, macOS or Linux.
• A Nextcloud account with Talk and an app password (Settings → Security → App passwords) — not your login password.
• A running opencode serve. Tested against OpenCode 1.15.11; expected compatible with the OpenCode 1.15+ HTTP API until it changes. Default endpoint http://127.0.0.1:4096.

Install

One command — installs the opencode-talk-bridge CLI from PyPI into an isolated environment and onto your PATH (uv or pipx):

uv tool install opencode-talk-bridge
# or:  pipx install opencode-talk-bridge

For the unreleased latest commit, install from git instead: uv tool install git+https://github.com/leiverkus/opencode-talk-bridge.git.

Then create your config interactively and run:

opencode-talk-bridge --init     # interactive .env wizard (chmod 600)
opencode-talk-bridge --check    # validate config + OpenCode health
opencode-talk-bridge            # run (reads ./.env, or pass --env-file PATH)

--init asks only for the essentials; every other option keeps a safe default and can be added later (see .env.example for the full list).

First run against a real Talk server? Follow the end-to-end smoke test — it tests the riskiest paths first and covers the two-accounts gotcha.

Upgrade with uv tool upgrade opencode-talk-bridge (or pipx upgrade …).

git clone https://github.com/leiverkus/opencode-talk-bridge.git
cd opencode-talk-bridge
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"         # editable + test/lint tools
cp .env.example .env            # then edit .env

The OCS client is the separate nextcloud-talk-core package from PyPI (tracking the 1.x line) — never reimplemented or vendored here.

Configure

Edit .env (see .env.example for the full list):

ALLOWED_USERS must be the stable user ID (the login, e.g. jdoe), not the display name. The bridge matches the OCS actorId with actorType == "users", so guests and bots can never impersonate an allowed user even if display names collide.

Run

# Validate config + check OpenCode health, then exit:
opencode-talk-bridge --check

# Run the bridge (foreground):
opencode-talk-bridge            # or: python -m opencode_talk_bridge

Commands (in Talk)

Send any message (or a voice note / file) to prompt OpenCode. The reply streams live into one message as it is generated. Slash-commands:

/projects lists every project the OpenCode backend knows (same as the desktop app). /sessions, /commands, and /skills are project-scoped: they show what the conversation's current project shows — pick a project with /projects (or set a default OPENCODE_DIRECTORY). With no project bound, /sessions falls back to a global list across all projects.

No inline buttons on Talk → every picker is a numbered list: reply with the number. When OpenCode asks permission for a dangerous action, reply ja (allow once), immer (allow for this session), or nein (deny); agent questions are answered by their option number or free text.

Set BOT_LOCALE=en for English UI strings (default de).

Run under launchd (macOS)

A user-agent example is in deploy/. Edit the paths, then:

cp deploy/com.leiverkus.opencode-talk-bridge.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.leiverkus.opencode-talk-bridge.plist
# stop / uninstall:
launchctl bootout gui/$(id -u)/com.leiverkus.opencode-talk-bridge

Secrets stay in .env (read from WorkingDirectory), never in the plist.

Status file (menubar-app contract)

The bridge atomically writes STATUS_FILE (JSON) on every state change. A supervising app (e.g. the Swift menubar app) can poll it. The file is always valid JSON (temp-write + rename). Schema:

{
  "state": "polling",
  "since": 1748600000,
  "opencode_healthy": true,
  "conversations": ["abcdef12"],
  "last_error": null,
  "version": "0.1.0"
}

state ∈ starting · polling · working · opencode_down · error · stopped. since is a Unix timestamp; conversations lists watched tokens; last_error is a human-readable string or null.

Threat model

This bridge executes coding-agent actions on your machine (file writes, shell commands via OpenCode), triggered by chat messages in a Nextcloud Talk instance you may not administer (e.g. a university server). Treat that Talk instance as semi-trusted infrastructure. The trust boundary and mitigations:

• Access control is the allowlist. Only actorType == "users" IDs in ALLOWED_USERS can issue commands; every other message is ignored. An empty allowlist aborts startup. Anyone who can post as an allowlisted user can run code as you — keep the list minimal and the control conversation private.
• Dangerous actions require confirmation. OpenCode's permission prompts (shell, file writes) are surfaced into Talk and must be answered; nothing runs without a ja/immer. Configure OpenCode's own permission policy conservatively as defence in depth.
• Secrets are never echoed. The bridge does not post your app password or tokens, and permission prompts show only the action kind and a length-capped pattern — not raw command arguments that might contain secrets. Be aware that OpenCode's answer text itself could contain sensitive repo content; it is posted into Talk, whose admins can read it.
• A compromised Talk server could inject messages appearing to come from an allowlisted user. The allowlist mitigates casual misuse, not a fully compromised IdP/server. Do not point this at sensitive repos if that is your threat model.
• Local-only OpenCode. Keep opencode serve bound to 127.0.0.1. If you expose it, secure it with OPENCODE_USERNAME/OPENCODE_PASSWORD.

To report a vulnerability, see SECURITY.md (please don't open a public issue).

Stability

This project follows SemVer. From 1.0.0, the following are the stable public contract — breaking changes to them only happen on a major bump:

• CLI: the opencode-talk-bridge command and its flags (--init, --check, --env-file).
• Configuration: the documented .env keys (see .env.example) and their meaning.
• Talk commands: the slash-command names (/new, /sessions, …).
• Status file: the JSON schema and its state values.
• State store: SQLite migrations stay forward-compatible — upgrading never requires deleting your database.

Not covered (may change in any release): the Python module/API layout, exact wording of bot replies and log lines (the i18n strings), and which OpenCode/Nextcloud versions are supported.

Pre-1.0.0 (the current 0.x line) these may still change between minor versions; pin a version you have tested.

Development

pip install -e ".[dev]"
ruff check src tests
ruff format --check src tests
pytest

All tests use mocked HTTP for both Talk and OpenCode — no live calls. CI runs the matrix on Python 3.10–3.13. Dev setup, conventions, and the (one-command) release process are in CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

License

MIT © Patrick Leiverkus