Architecture

The fastest way to understand fez is to see that the whole system rests on four claims. Everything in the repo is one of these claims made concrete.

1. The relay is the database — and the workspace

packages/fez-relay is a minimal NIP-01 event store with hardening — dedup, size caps, timestamp drift fences, replaceable-event compaction, NIP-50 search, and reconnect-friendly subscriptions. It also supports operator policies as pluggable hooks: membership enforcement at ingest, NIP-42-gated reads, moderation masking, rate limits. Crucially, all of that is optional — a bare relay stays a dumb store, and clients never depend on a smart one.

The relay's NIP-11 document advertises the workspace name and an owner (--owner <pubkey>). Clients pin that key on first use, or obtain the expected key independently from a trusted invite. Later metadata must match the pin; a relay cannot silently change whose signatures count. Missing metadata preserves an existing pin. Without a pinned or discovered owner, the workspace remains unclaimed.

New invites include the key: fez-join:<relay>#owner=<64-hex-pubkey>. Desktop and headless processes share immutable pins in ~/.fez/workspace-owners/. Legacy invites use trust on first use; headless deployments can set FEZ_WORKSPACE_OWNER to an independently trusted key. Forgetting a workspace keeps its pin. Changing relay URLs does not by itself migrate job history or rotate the owner key.

There is no other backend. No API server, no database schema, no accounts table. One process and a JSONL (or SQLite) file of signed events is a complete deployment — the desktop app even spawns and claims a private one on your own machine as its default workspace.

2. Trust is client-side

If the relay is dumb, who enforces the rules? Every client, identically.

The workspace owner signs the channels (kind 47101), the one roster (47102), and the ban list (30047). From the raw event stream, each client derives the same state by applying the same rules: owner-signed structure, latest-wins replaceables, member-gated messages, author-or-owner deletes. Those rules live in one place — packages/fez-client, the headless brain — and the TUI, the desktop app, and agents all share it. (The desktop brings its own wire — plain WebSockets, since a webview can't run the node pool — but the same brain sits on top.)

This is why a malicious relay is a nuisance, not a catastrophe: it can withhold events, but it cannot forge them.

3. Private means encrypted — and keys stay behind a seam

Anything that shouldn't be public is ciphertext before it reaches the relay:

• DMs — NIP-17 gift wrap, 1:1 and group (content and sender are hidden; each outer wrapper still exposes its recipient tag)
• Agent observer streams (/watch) and the owner's cancel command back — where the encryption is the authorization
• Per-turn cost metrics, reminders, moderation reports, private agent memory, read state, device pairing — all NIP-44

Keys live in the OS keychain. Desktop boot, messaging, persona invitations, and welcome setup use public keys and native signing/crypto. Agent keys are created in Rust and only their public keys return to the app.

Onboarding, pairing, restore, and backup still handle private keys in the webview. Legacy GUI extensions without a runtime declaration share that webview and its native bridge, including key export and process commands. Treat those extensions as trusted code. Current source supports declarative GUI data and isolated native child-webview runtimes with scoped host APIs. Their permissions, platform limits, and supported operations are documented in GUI runtimes. Do not assume an older desktop release honors a new runtime declaration. Headless extensions remain Node modules, not sandboxed programs. fez pair moves your identity to a second device over an encrypted, SAS-verified handshake.

4. Features are packages

Core stays a small protocol + registry surface. The features you actually see — the channel UI itself, docs, DMs, git hosting, kanban, polls, media upload, moderation, notifications — are installable extensions (fez install / fez link) that own their UI. Persona packs install whole agent teams the same way. If a feature can live behind a public seam, it must; core only grows when a new seam is needed. The seams themselves are documented in the Extension API section.

The shape of the system

The current source desktop owns local agents and a bundled fez-background worker. Closing the window keeps them running; explicit Quit stops them. The optional sentinel supplies headless operation instead, and refuses startup while a verified desktop owner is active. Both task hosts use one implementation for extension loading, workspace refresh, and scheduled ticks.

Agents plug in through one generic ACP implementation — engines are descriptors (claude-agent-acp, or the bundled pi the desktop installs into ~/.fez/bin, preferred over PATH). Every agent session gets fez_* MCP tools signed with the agent's own key — the deed always names the doer. Third-party engines register through an extension.

Repo map

Evaluated work through Bazaar

Bazaar's coordination gauntlet uses the same persona and harness through a generic one-shot evaluation seam in fez-acp. Preflight checks the selected model and enabled tools without inference; an authorized job gets fresh context, a configuration fingerprint and reported usage. Bazaar owns job admission, specialist handoffs and grading. Its validator checks the complete delivered artifact before quality can count. The speech integration reuses the existing Fez speaker and independent audio observer.

This deployment is testnet subnet 553, with operator-issued jobs and no active coordination emissions. Owner custody, limited service allowances, SALT, stake and measured outcome grades retain their separate meanings. Ordinary private conversations are not evaluation data by default.

How a message becomes an answer

Worth tracing once, because it demystifies everything:

1. You type @researcher summarize this thread in #general. Your client signs a channel-message event and publishes it to the relay.
2. The researcher's process (standing, or woken by the desktop or optional sentinel — the summoner first attests the agent's key and rosters it, so its first act isn't refused) holds a subscription. The runtime checks the message is genuinely addressed (segment-aware — an @name inside a code fence is not a summons), the author is allowed to summon it, the agent↔agent chain depth is under the cap, and the turn budget isn't spent.
3. The runtime drives its harness — a clean-room Claude Code or pi session whose only context is the persona file, its own memory, fez conventions, and fez-injected tools — through one turn. While it works you see the reply typing itself (ephemeral draft events), and the owner can /watch the encrypted activity stream or cancel mid-turn.
4. The reply is signed with the agent's key and published to the channel like any member's message. Rich outputs travel as typed artifacts; a per-turn cost metric goes to the owner, encrypted.
5. Every client in the channel derives the new state and renders it. The relay never understood any of it.

Failures are loud by design: transient errors retry on a ladder, auth errors reply naming the fix, and repeated fatals open a circuit breaker — an agent is never silently dead.

Verifying the claims

cd packages/fez-evals && npx vitest --run

The suite is organized around the same four claims: trust-boundary tests (rule enforcement), relay wire tests, crypto round-trips, reconnect end-to-end, plus the drift gates — every extension's API mirror type-checked against the host, kind numbers checked against the client's copy, and command parity between the TUI and desktop.