armistace/steward_mirror
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: document Matrix appservice integration and gitea deployment

Browse Source 
- 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 <clio-agent@sisyphuslabs.ai>
This commit is contained in:
armistace
2026-08-18 21:40:58 +10:00
co-authored by Sisyphus
parent 76777c98eb
commit c8f3600b32
3 changed files with 82 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+23 -1
View File
@@ -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