8000 GitHub - hasanen/botrix · GitHub
[go: up one dir, main page]

Skip to content
hasanenPublic

Repository files navigation

Botrix

A self-hosted Matrix notification gateway. Botrix receives HTTP webhooks from external services and forwards formatted messages to Matrix rooms, and it works in the other direction too: mention the bot in a room to call an external webhook and get the result back. No custom code required per integration, just YAML configuration.

This project is fully AI-driven. All code, documentation, and architecture decisions are generated by AI tools. Human involvement is limited to requirements, review, and approval.

What it does

  • Exposes a single dynamic webhook endpoint: POST /api/v1/webhooks/notify/:identifier
  • Maps each identifier to a Matrix room destination via YAML config
  • Renders messages from payload data using a simple ${variable} 8000 template syntax
  • Sends encrypted messages to Matrix rooms (E2EE)
  • Runs command triggers: mention the bot (@botrix deploy prod) to call an HTTP webhook and reply in the room with the result
  • Provides a web UI for managing connections, tokens, trigger secrets, and notification history

Screenshots

The admin web UI, shown with the example config.

Webhook endpoints Command triggers
Matrix account and destinations Logs

Project status

Botrix is at v1.0.0 and carries messages in both directions. Inbound: webhook intake and templating, the delivery queue with retries, and end-to-end-encrypted room delivery (after a one-time recovery-key import). Outbound: command triggers that call your webhooks from a Matrix room. It also has the admin web UI, connecting a Matrix account over OAuth, and the container image. Connecting a Matrix account needs a homeserver running Matrix Authentication Service and Botrix reachable at an HTTPS URL — see the Matrix setup guide.

Quick start

# Pull the image
podman pull ghcr.io/hasanen/botrix:latest

# Run with a config file and persistent data volume
podman run -d \
  --name botrix \
  --restart unless-stopped \
  -p 8080:8080 \
  -v /your/config:/config:ro \
  -v /your/data:/data \
  -e BOTRIX_SESSION_SECRET=your-secret-here \
  -e BOTRIX_CRYPTO_PASSPHRASE=your-passphrase-here \
  ghcr.io/hasanen/botrix:latest

Open http://localhost:8080 to create the admin account.

  • Both secrets must be set, BOTRIX_SESSION_SECRET must be at least 32 characters, and the two values should differ. openssl rand -base64 32 makes a good one.
  • Browsers only accept the session cookie over HTTPS (or localhost). For a quick trial over plain HTTP on another host, add -e BOTRIX_INSECURE_COOKIES=1; otherwise put Botrix behind an HTTPS reverse proxy.
  • Botrix has no built-in rate limiting. Run it behind a reverse proxy that provides it (see the deployment guide).

Command triggers

The reverse direction: mention the bot in a Matrix room (@botrix <command> args) and Botrix calls an external HTTP webhook, then replies in the room with the result.

  • Triggers and reusable access profiles are defined in the YAML config (triggers, access_profiles), so they live in version control. Changes need a restart. The Triggers page in the web UI lists them and sets their secret values.
  • Commands match case-insensitively on the first word after the mention. help is built in and lists only the commands the sender can run in that room.
  • The request payload has fixed keys: command, arguments, args, raw_message, sender, room_id, event_id.
  • The reply is the JSON response rendered through the same ${field.path} templates as webhooks. Non-JSON or failed calls reply with a short success or failure notice; details go to the logs.
  • Header values can reference secrets with {{secret:NAME}}. The config declares secret names only; the values are set in the web UI, encrypted at rest and write-only: the API and UI never show them again, only that they are set. Never put credentials in the config file. Botrix refuses to start if Authorization, Cookie or similar headers hold a literal value.
  • Access control: each trigger can limit allowed rooms and users. Both must match (AND). An empty list means unrestricted. Inline lists override the trigger's access profile.
  • Outbound calls are SSRF-guarded: loopback, private, link-local, unique-local, unspecified and multicast addresses are blocked, redirects are not followed, and requests have timeouts and a response size cap.
  • Replies are not retried. A command is never replayed, so a failure is reported once in the room.
  • Every command that runs, is refused or fails is logged with the sender and room. View activity on the Triggers page opens the Logs page filtered to that command, and the Logs page can also be filtered by component and command.

Documentation

Full documentation is available at hasanen.github.io/botrix.

License

MIT

Releases

Packages

Used by

Contributors

Languages

0