Skip to content

Monolith documentation

Monolith is an atproto PDS that keeps its state in write-ahead logs on local disk, with no database beside it. It speaks the same XRPC, OAuth and firehose as the reference PDS (@atproto/pds), so the Bluesky app, relays and AppViews talk to it like any other PDS.

How to do things with Monolith, one task at a time. You don’t need a clone of the repository to run it, only to contribute.

  • Getting started: get the image or the binary, configure it, run it behind your proxy, make the first account and sign in from Bluesky.
  • Calling the server: XRPC, the pds CLI, the MCP endpoint, and connecting an AI app.
  • Deploying: the image, the proxy, the environment, blobs in a bucket and backups.
  • Operating: the log, health, metrics, traces, stopping, upgrades, disk and memory.
  • Comparing with the reference: the harness’s runs, performance, the benchmark and the compatibility check.
  • Contributing: working from a clone, a server to try with just dev --seed, the just targets, the gates, nightly, the code gates and releases.
  • Compatibility: how closely other PDSes behave like the reference, and how to add one.
  • Benchmark: the server beside other PDSes, how to run it and the fairness rules.