Synclean

Synclean is a Python library and command-line tool for inspecting and cleaning media on a Matrix Synapse homeserver. It connects to the Synapse Admin API, exposes reusable core services, and provides Click commands for common administration workflows.

The project is built for homeserver maintenance work: find the largest media consumers, inspect a user's uploads, review room media, preserve important avatar references, and run cleanup operations deliberately.

Features

• View user details, joined rooms, avatar, media count, and media size.
• View room details, members, creator, avatar, room type, and media counts.
• Search and paginate large user and room lists.
• Inspect per-user media usage from Synapse media statistics.
• List user media by size, date, ID, or MIME type.
• Delete selected user media and room media through the Synapse Admin API.
• Purge room history using separate retention policies for bridge rooms and regular rooms.
• Import and track user avatars, room avatars, and stickers in MariaDB-backed tables.
• Manage homeserver, access token, database, ignored users, and purge settings from the CLI configuration file.

Requirements

• Python 3.12 or newer
• A Matrix Synapse homeserver with Admin API access
• A Synapse admin access token
• MariaDB or MySQL-compatible database access for avatar and sticker tracking

Installation

Clone the repository, then install the project and its dependencies:

git clone <repo-url>
cd Synclean
uv sync

If you are not using uv, install it with another Python package workflow:

python -m pip install -e .

Configuration

Synclean stores its settings in your user config directory as synclean/config.yaml. On Linux this is typically:

~/.config/synclean/config.yaml

Create or update this file with:

synclean settings

The configuration contains:

• username: the Synapse admin username used by the app
• homeserver: your homeserver URL, for example https://matrix.example.com
• access_token: an admin access token
• database: MariaDB connection settings
• ignored_users: users that should be ignored by cleanup-related workflows
• room_history_purge: retention periods for regular rooms and bridge rooms

Example:

username: "@admin:example.com"
homeserver: "https://matrix.example.com"
access_token: "YOUR_ADMIN_ACCESS_TOKEN"
room_history_purge:
  bridge_room_policy:
    retention_period: 7
  regular_room_policy:
    retention_period: 0
ignored_users: []
database:
  name: "synclean"
  host: "127.0.0.1"
  port: 3306
  username: "synclean"
  password: "password"
user_agent: "Synclean/1.0"

Retention periods are stored as days. A value of 7 means Synclean will purge room history older than seven days when that policy is used.

Running the CLI

After installation, inspect the available commands with:

synclean --help

Implemented command groups include:

• user ls, user show, and user media
• room ls and room show
• media ls and media delete
• settings

Python Library

The synclean package can also be imported by other Python code. Core modules are organized under:

• synclean.api: Synapse Admin API clients and repositories
• synclean.services: workflows that coordinate API and database operations
• synclean.models: Pydantic request, response, and domain models
• synclean.database: MariaDB/MySQL persistence helpers

Safety Notes

Synclean performs real administrative cleanup operations against Synapse. Deleting media and purging room history can be irreversible, depending on your server configuration and backups.

Before running deletion workflows:

• Confirm the homeserver and admin token point to the intended server.
• Review media lists and usage totals first.
• Use conservative thresholds.
• Keep backups or snapshots for important deployments.
• Be especially careful with room media deletion and history purging.

Development

Install development dependencies:

uv sync --group dev

Run checks:

uv run ruff check .
uv run pyright
uv run pytest

Project layout:

src/synclean/api/        Synapse Admin API clients and repositories
src/synclean/cli/        Click command groups
src/synclean/config/     YAML configuration loading and saving
src/synclean/database/   MariaDB persistence for avatars and stickers
src/synclean/models/     Pydantic models and domain objects
src/synclean/services/   Application service layer
src/synclean/utils/      Logging, formatting, and shared helpers

Build publishable artifacts with:

uv build

Publish them with uv publish after configuring the target index credentials.

License

This project is licensed under the terms in LICENSE.