From c8f3600b32401da74ad3b36f5bfa182806b438d6 Mon Sep 17 00:00:00 2001 From: Andrew Ridgway Date: Tue, 18 Aug 2026 21:40:58 +1000 Subject: [PATCH] docs: document Matrix appservice integration and gitea deployment - Add Matrix bot to the feature list and prerequisites. - Add a Matrix Appservice section covering config, Synapse registration, and the shared conversation pipeline. - Document the matrix config section in CONFIGURATION.md. - Add a ready-to-use Synapse appservice registration template (matrix/steward_appservice.yaml). - Document the Gitea Actions build/deploy workflow and kube manifests. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- CONFIGURATION.md | 30 ++++++++++++++++++++++++++++++ README.md | 24 +++++++++++++++++++++++- matrix/steward_appservice.yaml | 29 +++++++++++++++++++++++++++++ 3 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 matrix/steward_appservice.yaml diff --git a/CONFIGURATION.md b/CONFIGURATION.md index b19bb3f..6771c48 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -199,6 +199,36 @@ tools: - `STEWARD__TOOLS__MCP_SERVER_URL` - `STEWARD__TOOLS__MCP_SERVER_API_KEY` +### Matrix Section + +```yaml +matrix: + homeserver_url: "" # Homeserver client-server base URL (e.g. http://matrix:8008) + homeserver_domain: "" # Homeserver server_name (e.g. matrix.aridgwayweb.com) + as_token: "" # Appservice token (authenticates to the homeserver) + hs_token: "" # Homeserver token (authenticates incoming transactions) + bot_localpart: "steward" # Bot user localpart -> @steward: + appservice_id: "steward" # Unique appservice ID + listen_host: "0.0.0.0" # Appservice HTTP server host + listen_port: 8000 # Appservice HTTP server port + allowed_room_ids: [] # Room allow-list (empty = all rooms) + allowed_user_ids: [] # User MXID allow-list (empty = all users) +``` + +**Environment Variables:** +- `STEWARD__MATRIX__HOMESERVER_URL` +- `STEWARD__MATRIX__HOMESERVER_DOMAIN` +- `STEWARD__MATRIX__AS_TOKEN` +- `STEWARD__MATRIX__HS_TOKEN` +- `STEWARD__MATRIX__BOT_LOCALPART` +- `STEWARD__MATRIX__APPSERVICE_ID` +- `STEWARD__MATRIX__LISTEN_HOST` +- `STEWARD__MATRIX__LISTEN_PORT` +- `STEWARD__MATRIX__ALLOWED_ROOM_IDS` - Comma-separated list of room IDs +- `STEWARD__MATRIX__ALLOWED_USER_IDS` - Comma-separated list of user MXIDs + +The Matrix bot is enabled when `homeserver_url`, `as_token`, and `hs_token` are all set. See [`matrix/steward_appservice.yaml`](matrix/steward_appservice.yaml) for the Synapse appservice registration template. + ## Environment Variable Format Environment variables follow the pattern: `STEWARD__SECTION__KEY=value` diff --git a/README.md b/README.md index 74251d3..7c1d822 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ Steward is a long-running, AI-assisted personal operations platform designed to ## Features - **Telegram Bot**: Group/channel support with thread-based conversations +- **Matrix Bot**: Native Matrix application-service (appservice) integration via Synapse - **Message Threads**: Organized conversations with automatic summarization - **Knowledge Base**: Stores and retrieves conversation summaries - **LLM Integration**: OpenAI-compatible API support @@ -17,8 +18,9 @@ Steward is a long-running, AI-assisted personal operations platform designed to - Python 3.12+ - Docker & Docker Compose -- Telegram Bot Token (from [@BotFather](https://t.me/botfather)) +- Telegram Bot Token (from [@BotFather](https://t.me/botfather)) — required for the Telegram bot - OpenAI API Key +- A Matrix homeserver (e.g. Synapse) — required for the Matrix appservice bot ### Local Development @@ -48,6 +50,24 @@ docker compose -f docker-compose.dev.yml up --build See [CONFIGURATION.md](CONFIGURATION.md) for detailed configuration options. +### Matrix Appservice + +Steward can run as a native Matrix bot by registering it as a Synapse application service. When configured, it receives room events via HTTP transactions and replies through the client-server API, reusing the same conversation pipeline as the Telegram bot. + +To enable it: + +1. Configure the `matrix` section (via `STEWARD__MATRIX__*` env vars or a config file): + - `homeserver_url` — the homeserver client-server base URL (e.g. `http://matrix:8008`) + - `homeserver_domain` — the server name (e.g. `matrix.aridgwayweb.com`) + - `as_token` / `hs_token` — the appservice tokens + - `bot_localpart` — the bot user localpart (defaults to `steward`) + - `listen_host` / `listen_port` — where the appservice HTTP server listens + - `allowed_room_ids` / `allowed_user_ids` — optional allow-lists + +2. Register the appservice with Synapse. See [`matrix/steward_appservice.yaml`](matrix/steward_appservice.yaml) for a ready-to-use registration template, and add it to your `homeserver.yaml` under `app_service_config_files:`. + +3. Start Steward. It will run the Telegram bot, the Matrix appservice, or both depending on which are configured. + ### Running Tests ```bash @@ -86,6 +106,8 @@ On every commit. You can skip with `git commit --no-verify` if needed. For Kubernetes deployment, see examples in [CONFIGURATION.md](CONFIGURATION.md#kubernetes). +The repo includes a Gitea Actions workflow (`.gitea/workflows/build_push.yml`) that builds a multi-arch Docker image, pushes it to the gitea registry, and deploys to Kubernetes using the manifests in [`kube/`](kube/). The deployment uses a NodePort service exposing port 30002 (the Matrix appservice endpoint) and a persistent volume for thread memory. + Production image: `ghcr.io/djw4/steward:latest` ## License diff --git a/matrix/steward_appservice.yaml b/matrix/steward_appservice.yaml new file mode 100644 index 0000000..9462888 --- /dev/null +++ b/matrix/steward_appservice.yaml @@ -0,0 +1,29 @@ +# Steward Matrix appservice registration for Synapse. +# +# Copy this to the Synapse config dir (e.g. /config/steward.yaml) and add to +# homeserver.yaml: +# +# app_service_config_files: +# - /config/steward.yaml +# +# Then restart Synapse. The appservice bot user @steward:matrix.aridgwayweb.com +# is created automatically from sender_localpart; no register_new_matrix_user +# step is needed. +# +# The `url` must be reachable from Synapse. In-cluster this is the Steward +# appservice NodePort (30002) or an in-cluster service URL. + +id: "steward" +url: "http://:30002" +as_token: "" +hs_token: "" +sender_localpart: "steward" +rate_limited: false +namespaces: + users: + - exclusive: false + regex: "@steward:matrix\\.aridgwayweb\\.com" + aliases: + - exclusive: false + regex: "#steward.*:matrix\\.aridgwayweb\\.com" + rooms: []