Getting started on perch docs

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Prebuilt binaries for Linux, macOS, and Windows are published on the releases page. Every release includes SHA-256 checksums, SBOMs, a keyless cosign signature, and GitHub build provenance. See RELEASING.md for verification details.

With Go

If you have Go 1.26.4 or later, go install builds the latest tagged release. CGO is not required.

go install github.com/synqronlabs/perch/cmd/perch@latest

The binary is written to $(go env GOPATH)/bin (usually ~/go/bin). Add that directory to PATH if needed. To pin a version:

Create an mxRaven API key

Mon, 01 Jan 0001 00:00:00 +0000

perch setup needs an mxRaven API key to provision your workspace. mxRaven uses ZITADEL for identity, so the key is a Personal Access Token (PAT) on a ZITADEL service account.

This is a control-plane token, not a listener API key. perch uses it only during setup to create the domain, listeners, routes, and listener credentials, and never writes it to perch.yaml.

Before you start

You can sign in to the mxRaven dashboard.
You know your workspace slug, for example my-workspace. It is the --workspace value you pass to perch setup.
You have administrator access to that workspace.

1. Open the ZITADEL console

Sign in at https://id.mxraven.com/ui/console with the same account you use for mxRaven. You can also open the dashboard user menu and choose Manage authentication.

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

This quickstart provisions mxRaven, creates a local account, starts perch, and connects a mail client.

1. Provision mxRaven and generate config

First create an mxRaven API key, then export it. With the token, perch setup configures your domain, inbound route, submission listener, spam/auth rules, and writes perch.yaml:

export MXRAVEN_API_TOKEN=...

perch setup \
 --config ~/.local/share/perch/perch.yaml \
 --data-dir ~/.local/share/perch \
 --workspace my-workspace \
 --domain example.com \
 --hostname localhost

Publish the DNS records printed by the wizard, or pass --wait to wait until DNS verifies.