# Install

> Install the Weald relay on your own host. The three commands, what the bundle starts, first boot, and how to point the Mac app at it.

Source: https://getweald.com/docs/install
Last modified: 2026-08-03

---

## Install the relay

Last updated 2026-08-03

Installing a Weald relay is three commands: fetch the bundle, set a hostname, start it. First boot migrates the database, issues a certificate and prints a bootstrap invite you have twenty-four hours to redeem. Read requirements first if you have not picked a host yet.

## Run the install

```sh
curl -fsSL https://get.weald.team/relay | sh
cd weald-relay && cp .env.example .env && $EDITOR .env
docker compose up -d
```

The relay is published: wealdrelay-v0.1.5, built reproducibly and pinned by digest. It pulls ghcr.io/weald-protocol/wealdrelay@sha256:e78268855dd932bb06ce975bacda3fd8df6a4c28aa728838b356b3f61866c117.

The environment file that opens in the second command needs one value from you, the hostname. Everything else has a default that works, and Configuration covers the ones worth changing.

## What starts

*What the compose bundle runs*

| Container | Job |
| --- | --- |
| relay | The Weald relay itself, serving the client WebSocket over TLS |
| postgres | Envelopes, access sets, invites and the transparency log |
| object storage | Encrypted media blobs, which the relay has no key for |
| redis | Live fanout between relay processes, never a source of truth |
| tls | Certificate issuance and renewal on port 80 and 443 |

Redis carries fanout only. Losing a Redis message costs a subscriber a live push and is repaired by reconciliation on the next round trip, so it is never the reason an envelope was or was not accepted.

## First boot

First run migrates the schema and generates a single-use genesis key, then prints two things:

- A one-time enrollment URL carrying the relay hostname, the genesis-key fingerprint and the TLS-key fingerprint.
- The genesis fingerprint on its own, which is the value every later transparency-log entry chains back to.

Copy both before you close the terminal. The URL expires after twenty-four hours or on first use, whichever comes first, and the first device to open it becomes the workspace trust root.

The genesis private key is destroyed in the same transaction that redeems the invite. Bootstrap authority is never reissued, so there is no support path that recreates it. Reissuing works only while a workspace still has no trust root at all.

## Point the app at it

Install the Mac app, then open the enrollment URL on the machine you want to be the first admin. The app asks for the relay hostname and the enrollment link, checks the genesis fingerprint against the one the relay printed, and walks you through the recovery phrase before it touches the relay.

First workspace covers that sequence and the invites that follow it.

## Check it is healthy

The public listener serves liveness only. Detailed readiness and metrics bind to a private listener on loopback by default, so a self-hosted relay does not publish its storage totals and security state to the internet.

- GET /healthz on the public listener answers whether the process is alive.
- GET /readyz on the private listener answers whether Postgres and object storage are reachable, and reports whether the access set is being enforced.

If setup fails, the health check names the dependency that failed in words instead of printing a certificate stack trace. Troubleshooting lists what each one means.