phantom

A Matrix homeserver in Rust, with a terminal admin console in Go.
Documentation

Warning

Early; do not deploy. Local accounts can register, chat, sync and be managed from the console or with !admin commands in the admin room. The server serves HTTPS itself when [global.tls] is set, supports room versions 1–12, and federates: two phantom servers join each other's rooms in versions 11 and 12. It has not yet been tried against Synapse or another implementation.

Part	What it is
phantom-core	config, errors, logging, Matrix event types, state resolution
phantom-database	RocksDB engine, typed columns, codecs, read pool
phantom-service	the service runtime and its ~55 services
phantom-api	client-server, federation, OIDC and admin HTTP routes
phantom-macros	proc macros, including the config-example generator
phantom-server	the server binary
cli/	the phantom admin console

Quick start

Needs Rust 1.97.1 (pinned), Go 1.27+, a C/C++ compiler with libclang for the bundled RocksDB. Recipes run with just or make. Per-platform packages are in docs/installation.md.

git clone https://github.com/HilthonTT/phantom.git && cd phantom
just build    # release server, plus the console at target/phantom

# phantom.toml
[global]
server_name = "phantom.test"
database_path = "/var/lib/phantom"
allow_registration = true
registration_token = "change-me"

./target/release/phantom-server -c phantom.toml   # listens on localhost:8008
./target/phantom                                  # --server URL to point elsewhere

The first account to register becomes admin. Register it with any Matrix client and the token, then sign in to the console with it.

The admin console

Sections on the left, a table in the middle, details on the right; ? lists the keys, : opens the command prompt, q quits.

• Chat works for any account: rooms, sending, typing, receipts, :join.
• Every other section is live for an admin: overview, users, devices, tokens, rooms, appservices, settings, tasks, services, federation, media, logs and abuse reports. Otherwise they show sample data, labelled as such.
• Actions: enter on a row, or a : command, to manage users, devices, tokens, rooms, media and reports, block servers, quarantine media, purge old history and media, reload the config, back up, or cancel a running task. s sorts. See docs/moderation.md. A deactivated account stays deactivated through a password reset; only reactivating it (:reactivate, or enter on its row) lets it log in again.

The same actions work as !admin commands in the admin room, for example !admin users list, !admin users reactivate bob or !admin rooms shutdown '#lobby:example.com'; !admin --help lists them.

See the documentation.

Configuration and development

phantom reads TOML under [global], layered from $PHANTOM_CONFIG, then -c files, then PHANTOM_ environment variables (__ nests). phantom-example.toml documents every option and is generated by cargo build; don't edit it. See docs/configuration.md.

just check (or make check) runs what CI does: fmt, clippy with -D warnings, the Rust tests, go vet and go test -race. See docs/development.md; docs/architecture.md covers the internals.

Upstream and license

phantom is a port of conduwuit and still tracks it (docs/upstream-sync.md); attribution is in NOTICE. Licensed under Apache-2.0. Contributions are welcome (CONTRIBUTING.md); report vulnerabilities privately (SECURITY.md).