Skip to content

netresearch/matrix-skill / skills/matrix-administration

matrix-administration

Verified

Use when administering a Synapse / Matrix homeserver — list or snapshot all rooms, rate room health (public, unencrypted, orphaned), render a Graphviz map of the room/space tree, force-join users, promote room admins, harden rooms (add-to-space + restrict + encrypt), deactivate Matrix users (with GDPR erase), find biggest rooms by DB size, audit where a user is admin or member, replay join/leave timelines, or search unencrypted history. Trigger on any '/_synapse/admin', server-wide room operation, Matrix user offboarding, or anything requiring a homeserver-admin token — even without 'admin API' in the prompt. Companion to matrix-communication.

references/room-graph-pipeline.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# Room graph pipeline

`synapse-graph.py` produces a Graphviz `.dot` file (and optionally an `.svg` via the system `dot` binary) showing every non-replaced room and its parent-space relationships. Edges go from a child room to its parent space; node colours and the gradient on space nodes encode the rating.

## Local one-shot

```bash
uv run skills/matrix-administration/scripts/synapse-fetch-rooms.py
uv run skills/matrix-administration/scripts/synapse-graph.py --space '!home:server'
xdg-open rooms.svg
```

`dot` must be installed (`apt install graphviz`, `brew install graphviz`, …). Pass `--no-svg` to emit only the `.dot` source.

## Periodic dashboard (Docker)

A common deployment is a static-file container that re-runs the snapshot+render at build time and serves the resulting SVG behind a reverse proxy. The Dockerfile below is a generic version of the upstream pipeline — drop in your own homeserver URL and reverse-proxy labels.

```dockerfile
# Builder: produce rooms.{en,de}.svg from a live snapshot
FROM python:3.13-slim AS builder
WORKDIR /app
RUN apt-get update \
 && apt-get install -y --no-install-recommends graphviz \
 && rm -rf /var/lib/apt/lists/*
# uv starts the scripts on Python 3.11 or later (here the image's 3.13)
COPY --from=ghcr.io/astral-sh/uv:0.13.1 /uv /bin/uv

COPY skills/matrix-administration/scripts ./scripts

# admin token mounted as a build secret
RUN --mount=type=secret,id=matrix_token \
    mkdir -p /root/.config/matrix && \
    cat <<EOF > /root/.config/matrix/config.json
{
  "homeserver": "${MATRIX_HOMESERVER:-https://matrix.example.com}",
  "admin_token": "$(cat /run/secrets/matrix_token)"
}
EOF

RUN uv run scripts/synapse-fetch-rooms.py
RUN LANGUAGE=en uv run scripts/synapse-graph.py && mv rooms.svg rooms.en.svg
RUN LANGUAGE=de uv run scripts/synapse-graph.py && mv rooms.svg rooms.de.svg

# Runtime: any tiny static-file server
FROM ghcr.io/thedevminertv/gostatic:1.5.2
CMD ["-cache","4h","-log-requests","-compress-level=2","-spa","-index","rooms.en.svg"]
COPY --from=builder /app/rooms.*.svg /static/
```

Build with:

```bash
echo -n "syt_admin_…" > /tmp/token
DOCKER_BUILDKIT=1 docker build --secret id=matrix_token,src=/tmp/token -t matrix-graph .
```

Schedule a rebuild however your platform prefers (cron + `docker compose build --no-cache && up -d`, a CI pipeline on a timer, a Kubernetes CronJob …).

## Reading the output

- **Green** node — all checks SUCCESS.
- **Orange** node — at least one WARNING, no FAIL.
- **Red** node — at least one FAIL.
- **Spaces** get a green→blue gradient when healthy, otherwise a flat orange/red.
- **Edges** are labelled `space child` and point from a room to the space that contains it.
- **Node tooltip** (visible in browsers / vector editors that honour SVG `title` attributes) lists every individual rating message.
- **Replaced** rooms (those that were upgraded and tombstoned) are dropped from the graph entirely.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall