Thatch

Thatch is the sync server for Ourcana. Ourcana devices push Willow entries to it over the Willow Transfer Protocol (WTP), and Thatch serves them back to any device holding a valid Meadowcap capability. Payloads are encrypted on the device before they leave it, so the server only ever stores ciphertext.

The same binary also runs a few small services the app relies on: a live-sync wake socket, a PluralKit dispatch relay, a friend-handshake mailbox, passkey vault envelopes, and read-only projection capabilities for the Discord bot.

Quick start

docker run -d --name thatch -p 8080:8080 -v thatch-data:/data code.heni.lol/ourcana/thatch:latest

In Ourcana, open Settings ▸ Backup and add ws://<host>:8080/wtp as a server. See SELFHOST.md for serving it over TLS with Caddy.

Images are built for linux/amd64 and linux/arm64 and published as code.heni.lol/ourcana/thatch.

Downloading binaries

Each release has a single thatch binary for Linux (static, amd64 and arm64), macOS (arm64, amd64 and universal), Windows (amd64 and arm64) and Android arm64 for Termux, plus a SHA256SUMS file to check them against:

curl -LO https://code.heni.lol/Ourcana/thatch/releases/download/v0.1.2/thatch-0.1.2-linux-amd64
curl -LO https://code.heni.lol/Ourcana/thatch/releases/download/v0.1.2/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
chmod +x thatch-0.1.2-linux-amd64
THATCH_DATA=./thatch-data ./thatch-0.1.2-linux-amd64

The macOS binaries aren't signed, so macOS will refuse to open a downloaded one until you run xattr -d com.apple.quarantine thatch-*-macos-*. In Termux, keep the binary somewhere under $HOME and run it from there. thatch --help lists the settings below. docs/releasing.md explains how the binaries are built and checked.

Configuration

Variable	Default	Meaning
THATCH_BIND	0.0.0.0:8080	Listen address.
THATCH_DATA	thatch-data (/data in the image)	Data directory: RocksDB, payload blobs and the server key.
THATCH_MAX_CONNS	1024	Maximum concurrent WTP WebSocket connections.
THATCH_ADMIN_TOKEN	unset	Enables GET /admin/usage behind Authorization: Bearer <token>.
THATCH_LOG_DIR	unset	Also write JSON logs to this directory, rotated daily, 14 files kept.
THATCH_ORPHAN_REPAIR	report	Startup scan for entries whose payload is missing or truncated: off, report or remove.
RUST_LOG	info	Log filter.
SENTRY_DSN	unset	Send errors and panics to Sentry. Unset turns reporting off.
SENTRY_ENVIRONMENT	test	production, qa or test. Anything else counts as test.

GET /health answers ok, and GET /metrics serves Prometheus metrics.

Sentry only gets errors and panics: the release, exception types and stack locations. Error messages, breadcrumbs, request data, user and context fields, and local variables are stripped before anything is sent, and there's no tracing or performance data. Protocol-only builds (default-features = false) leave Sentry out entirely. To check the scrubbing against a local endpoint, run cargo test -p thatch_server --lib --no-default-features --features server telemetry.

Building from source

cargo build --release --bin thatch

RocksDB needs clang and libclang. The workspace has three crates:

• crates/wtp_server (thatch_server): the WTP session, HTTP routes and the thatch binary. With default-features = false it is only the wire protocol (messages, capabilities, drop formats, payload hashing), without tokio, axum or RocksDB, for clients that speak WTP.
• crates/willow_store (thatch_store): entry and payload storage on RocksDB.
• crates/thatch_embed: a LAN-only server that the Ourcana app embeds.

License

AGPL-3.0-or-later. See LICENSE.