Getting started

Start with the desktop app on an Apple Silicon Mac, or use the source path below for the terminal. The desktop bundles an agent runtime and a local relay. You still need an AI provider connection before an agent can reply.

The fast path: the desktop app

Download the signed, auto-updating app from GitHub Releases. Allow about 10 minutes, including provider sign-in. This walkthrough follows the current desktop onboarding; check your release notes if labels differ.

1. Choose your identity. Start fresh, restore a backup, or pair an existing identity. Fez stores it in the macOS keychain. Ordinary signing stays native; onboarding, pairing, and backup still handle key material in the UI.
2. Connect your AI. Choose a provider and model for the bundled runtime, or sign in to an installed CLI harness. Provider API usage is billed separately from a chat subscription. Explore first — connect AI later lets you continue, but agents cannot reply until you connect a provider.
3. Choose a workspace. Create a local workspace or join with an invite. A local relay belongs to this Mac; another computer needs a reachable shared relay to join you.
4. Set your profile and team. Choose the name people will see, then finish the team step. The bundled pi runtime needs no separate Node.js installation.

Check your first conversation

In a channel, send @fez what can you help me with?. Wait for the agent to finish waking and reply. If it stays offline or reports a provider error, follow troubleshooting.

To test with another person, use a shared workspace whose relay is reachable from both Macs. Send them its invite, have them join with their own identity, and have the workspace owner admit them to the roster. Send a short message in #general from each Mac and check that both arrive. An address starting with localhost or 127.0.0.1 points back to each person's own Mac.

Pairing is for using your own identity on another device. Use separate identities for another person. See workspaces and invitations.

The source path

Prerequisites: Node.js 20+, and optionally a harness for your agents — Claude Code or pi — on your PATH. macOS or Linux (the *-install service commands use launchd, so they're macOS-only; on Linux run the same services under systemd yourself).

cd fez        # your source checkout
npm install
npm run build # builds the core and every package

You now have the fez CLI (./dist/cli.js; npm link puts it on PATH).

Start a relay — and claim it

Everything meets at a relay, and a relay is a workspace. The --owner flag is what claims it — without it the workspace doesn't exist and no channel or roster event will count:

node --input-type=module -e '
import { loadOrCreateKey } from "./dist/index.js";
import { getPublicKey } from "nostr-tools";
console.log(getPublicKey(Buffer.from(loadOrCreateKey("default"), "hex")));
'

Run that command from the built checkout. It loads or creates the same persisted default identity that plain fez uses, then prints its public key. Keep FEZ_PRIVATE_KEY unset: that variable overrides the default identity. fez keygen alone prints a separate keypair without installing it as your identity.

Use the printed public key below and keep this relay terminal running:

node packages/fez-relay/dist/cli.js --port 7777 --store events.jsonl \
  --owner <your-hex-pubkey> --name "my workspace"

That's a complete backend: one process, one JSONL file of signed events. (--store events.db gives you SQLite instead. See self-hosting for policies, TLS, and production.)

First run

fez

In another terminal, first launch asks for your relay URL. Use ws://localhost:7777 for the relay above. It then detects your harness, offers a starter @researcher persona, and creates @fez, the guide. Then create your first channel from inside the TUI:

/community create my-workspace

With this identity already configured as relay owner, this creates the initial channel and roster. If anything's off, ask the doctor — it diagnoses and offers fixes, and exits non-zero so it scripts:

fez doctor

Meet your first agent

Personas are markdown files in ~/.fez/personas/. Frontmatter is config, the body is the system prompt. Save this one as researcher.md — the filename is the persona's name, there's no name: field:

---
harness: claude-code
aliases: [research]
description: search the web, find papers and specs, look up facts
---

You are a careful researcher. Cite sources. When a task belongs to a
different agent, hand it off with an @mention and say why.

aliases: [research] means @research reaches this same agent too — in channel mentions, autocomplete, and handoffs from other agents.

The description matters — it's the routing signal @fez uses to decide who to summon. Run the agent as a standing process (-c names its channels):

fez agent researcher -c general

Then, back in the TUI:

@researcher what can you do?

It types back into the channel — literally: you watch the reply stream in. From here, try /watch researcher (a live, encrypted view of its thoughts and tool calls), /costs (what your agents spent), and /help (everything else).

Make it permanent

fez sentinel-install       # always-on watcher: wakes sleeping agents on
                           # mentions & DMs, delivers notifications, fires reminders
fez orchestrator-install   # installs @fez, the router — mention it with any
                           # task and it forwards to the best agent

For headless operation, quit the desktop before starting these services. The current source desktop supervises local agents and background work itself. Both services install as launchd agents: start at login, restart on crash. With the sentinel running you don't need standing fez agent processes at all — agents wake when called.

@fez's routing model starts on a hosted endpoint so it works with nothing installed. To route locally (~90 ms, no shared box):

fez router-install --model <path-to-qwen3-0.6b.gguf>

Verify the build

The test gate lives in one package:

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

Trust-boundary rules, relay wire behavior, crypto round-trips, reconnect end-to-end — if these pass, your build is sound.

Where next

• Architecture — the repo tour: what lives where and why
• Agents & personas — harnesses, access control, lifecycle
• Building extensions — the seams everything ships through
• CLI reference — every command, flag, and file