Overview
This guide shows you how to install, configure and operate your own go-ricochet server. There is no public Ricochet server, so running one is how you and your users get in.
What the server is
Section titled “What the server is”go-ricochet is a store-and-forward server for libp2p networks. Clients connect to it over libp2p, leave data for peers who are offline, and collect what was left for them when they come back. It works like an email MX server: the server holds mail until the recipient picks it up.
It stores:
- Mailboxes: folders of messages addressed to a peer, with IMAP-style flags. Private, shared and public types.
- Documents: key-value documents with ETags, conditional writes and merge-patch.
- Feeds: append-only feeds, optionally open to appends from any peer.
- Collections: keyed JSON items you can query.
- Directory: listings that peers publish about themselves and that any peer can search.
It also pushes notifications to clients: over a direct stream for private mailboxes, and over GossipSub for shared and public ones.
What a node does on the network
Section titled “What a node does on the network”Besides serving its own protocols, every server is a full libp2p node:
| Role | Default | Page |
|---|---|---|
| Circuit Relay v2 service: relays traffic for peers behind NATs | on | NAT traversal & relay |
| Kademlia DHT in server mode, for peer routing | on, always | DHT & bootstrap peers |
| GossipSub host: push notifications, presence, service discovery | on, always | Service discovery |
| Relay for GossipSub topics it does not use itself | off until you list topics | Relayed GossipSub topics |
The only transport is UDX, a reliable transport over UDP. Clients reach the server at a multiaddr such as
/ip4/203.0.113.10/udp/55223/udx/p2p/12D3KooW.... See Transport.
What it needs
Section titled “What it needs”- The
ricochetbinary. Release builds exist for Linux, macOS and Windows, plus.debpackages for Debian and Ubuntu. You can also build it with Go 1.25.7 or later. See Install. - PostgreSQL 14 or later. All state lives in PostgreSQL. The server does not create its schema; you load
schema.sqlonce. See Database setup. - One open UDP port, 55223 by default, reachable by your clients.
- A data directory for the server’s identity key, unless you supply the key another way. See Identity keys.
The server has no memory setting. It bounds work instead: connections, requests in flight, database pool size and the mailbox cache. Memory follows from those.
How it is configured
Section titled “How it is configured”Settings come from three layers, each overriding the one before:
- A preset: built-in defaults, or
--development,--productionor--high-capacity. See Presets. - A YAML file:
--config, or/etc/ricochet/config.yamlwhen it exists. - Command-line flags, and
RICOCHET_PG_PASSWORDfor the database password (applied before the flags).
A key the file leaves out keeps the preset’s value. A file that cannot be read or parsed, or that holds a key the server does not know, stops the server at startup. The full key list is in config.yaml, and every flag is in CLI flags.
Map of this guide
Section titled “Map of this guide”Get running
- Install: release archives,
.debpackages, building from source. - Database setup: role, database, schema, TLS and pool size.
- First run & your peer ID: start the server and give clients its address.
Capacity
- Presets: what each preset changes.
- Storage, quotas & retention: what fills up, and what happens when it does.
- Admission & rate limits: how the server bounds load.
Networking
- Transport, NAT traversal & relay, DHT & bootstrap peers, Service discovery, Relayed GossipSub topics.
Security
- Who can read what: the access model, and what the server can see.
- Trusted peers: private nodes and forwarding.
- Identity keys: the server’s Ed25519 key.
Operations
If you are building an app against a server, start with the Developer guide instead.