xomoxcc/openclaw-k8s-toggle-operator repository overview

⁠openclaw-k8s-toggle-operator

Matrix-controlled Kubernetes deployment toggle operator. Connects to a Matrix homeserver with E2E encryption and listens for chat commands to scale a K8s deployment between 0 and 1 replicas.

• Source: GitHub⁠
• PyPI: openclaw-k8s-toggle-operator⁠
• License: LGPLv3

⁠Features

• Scale a Kubernetes Deployment to 0 or 1 replicas via Matrix chat commands
• E2E encryption via minimatrix (matrix-nio wrapper) with persistent crypto store
• Session reuse — persists Matrix access token and device ID across restarts
• Auto-join pending room invites on startup
• TOFU device trust for allowed users
• Multiple auth methods: password, SSO, or JWT via Keycloak (ROPC + JWKS)
• Clean signal handling (SIGTERM/SIGINT) for graceful container shutdown
• Auto-reconnect with exponential backoff (max 20 retries)
• Structured logging via loguru

⁠Quick start

docker run --rm xomoxcc/openclaw-k8s-toggle-operator:latest

⁠Bot Commands

⁠Configuration

⁠JWT Authentication (Keycloak)

Set AUTH_METHOD=jwt to authenticate via Keycloak ROPC grant instead of direct Matrix password login. The bot obtains a JWT from Keycloak and presents it to Synapse for validation via JWKS.

Requires synapse-token-authenticator⁠ on the Synapse side. See the setup guide⁠ for step-by-step instructions.

⁠Kubernetes Deployment

The operator runs as a single-replica Deployment with a namespace-scoped ServiceAccount. The crypto store must be on a persistent volume or the bot loses decryption keys on restart. See the README⁠ for full RBAC and Deployment manifests.

⁠Image details

• Base: python:3.14-slim-trixie
• Non-root user (pythonuser)
• Entrypoint: tini -- with openclaw-k8s-toggle-operator as default CMD
• Requires libolm-dev for E2E encryption
• Multi-arch: linux/amd64, linux/arm64

⁠Building the image

# Simple local build
docker build -t openclaw-k8s-toggle-operator .

# Multi-arch build & push
./build-container-multiarch.sh

# Local-only build (no push)
./build-container-multiarch.sh onlylocal

# Docker Hub login only
./build-container-multiarch.sh login

⁠License

This project is licensed under the LGPL where applicable/possible — see LICENSE.md⁠. Some files/parts may use other licenses: MIT⁠ | GPL⁠ | LGPL⁠. Always check per‑file headers/comments.

⁠Authors

• Repo owner (primary author)
• Additional attributions are noted inline in code comments

⁠Acknowledgments

• Inspirations and snippets are referenced in code comments where appropriate.

⁠⚠️ Note

This is a development/experimental project. For production use, review security settings, customize configurations, and test thoroughly in your environment. Provided "as is" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. Use at your own risk.