~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
179 lines · 9.8 KB Raw History
# Monolith

Monolith is an atproto PDS that keeps its state in write-ahead logs on
local disk, with no database beside it. A write is synced before it's
answered, so it survives the server being killed at any moment. Each
account is loaded when it's first used, so memory stays within the
server's base, a cache (256 MiB by default) and 4 KiB an account, however
much the accounts hold.

![The consent page an app sends you to when it signs in with OAuth: the app, the account, what it asks for in plain words, and Allow, Deny and Back](docs/assets/consent.png)

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. It answers like the reference in every check of the
compatibility suite. Every method is also a `pds` command and an MCP tool,
so an AI app such as Claude can sign in and work with your account.

It's one Rust binary. In the benchmark it wrote records ~25 times as fast
as the reference (2,492/s against 99/s), started in 239 ms against 3.4 s,
and idled at ~20 MiB against ~378 MiB (on an M1 Pro, in Docker:
[bench/RESULTS.md](bench/RESULTS.md)).

## Highlights

- **Behaves like the reference.** Every area of the server is run beside
  `@atproto/pds` with the same seeded random requests, every answer is
  compared, and the server's whole repository is verified with the
  reference's own library. A difference fails the gates.
  → [Comparing with the reference](docs/guide/comparing.md),
  [Compatibility](compat/README.md)
- **Its own storage.** Writes waiting at the same time share one sync,
  whichever accounts they're for, through a shared journal (`PDS_SYNC`).
  The server compacts its logs in the background, so the data directory
  stays within three times what its accounts hold. Blobs can go in an
  S3-compatible bucket instead. → [Operating](docs/guide/operating.md),
  [STORE.md](spec/STORE.md)
- **Three ways to call it.** Every method is an XRPC call, a `pds` command
  and a tool on the MCP endpoint, all made from its lexicon. An MCP client
  signs in with OAuth on the server's own pages.
  → [Calling the server](docs/guide/calling.md)
- **OAuth and passkeys.** The server is the OAuth authorization server for
  its accounts, with its own sign-in and consent pages. An account can sign
  in there with a passkey instead of its password.
  → [OAUTH.md](spec/OAUTH.md), [PASSKEYS.md](spec/PASSKEYS.md)
- **Spaces.** It serves permissioned data from atproto's spaces proposal,
  OAuth `space:` permissions included, checked against the reference's
  pinned spaces alpha. → [SPACES.md](spec/SPACES.md)
- **Fast and small.** Beside the reference in the benchmark, it served the
  request mix at 2,483/s against 299/s, and peaked at 167 MiB against
  806 MiB. → [Benchmark](bench/README.md), [results](bench/RESULTS.md)

## Quickstart

You need a Linux server, a domain with a wildcard record under it, a
reverse proxy holding TLS for both, and an SMTP server.
[Getting started](docs/guide/getting-started.md) walks through each one.

```sh
docker pull knotless.dev/chadtmiller.com/monolith
```

Put the settings in `pds.env` (Getting started lists them), then run it
and check that it answers through your proxy:

```sh
docker run -d --name monolith --restart unless-stopped \
  -p 127.0.0.1:2583:2583 -v pds-data:/data --env-file pds.env \
  knotless.dev/chadtmiller.com/monolith
curl https://pds.example.com/xrpc/_health
```

Make an invite code as the admin, then the first account with it:

```sh
export PDS_URL=https://pds.example.com
PDS_ADMIN_PASSWORD=… pds server create-invite-code --use-count 1
pds server create-account --handle alice.pds.example.com \
  --email alice@example.com --password '…' --invite-code <the code>
```

The CLI is the same `pds` binary. With Docker, run it as `docker run --rm
-e PDS_URL -e PDS_ADMIN_PASSWORD knotless.dev/chadtmiller.com/monolith`.
The binary for Linux x86-64 is on the
[releases page](https://knotless.dev/chadtmiller.com/monolith/releases).

## Docs

The docs site is at https://chadtmiller-com.knotless.page/monolith/, built
from [`docs/`](docs/README.md), the spec and the reference pages.

| | |
| --- | --- |
| [Getting started](docs/guide/getting-started.md) | Get the image or the binary, configure it, run it, make the first account |
| [Calling the server](docs/guide/calling.md) | XRPC, the `pds` CLI, the MCP endpoint, connecting an AI app |
| [Deploying](docs/guide/deploying.md) | The image, the proxy, the environment, blobs in a bucket, backups |
| [Operating](docs/guide/operating.md) | The log, health, metrics, traces, upgrades, disk and memory |
| [Comparing with the reference](docs/guide/comparing.md) | The harness's runs, performance, the benchmark, the compatibility check |
| [Contributing](docs/guide/contributing.md) | Working from a clone, a server to try, the gates, releases |
| [PDS.md](spec/PDS.md) | The specification: what the server does, with a page for each area |
| [COMMANDS.md](spec/COMMANDS.md) | Every method as an MCP tool and a CLI command |
| [Compatibility](compat/README.md) | How closely other PDSes behave like the reference |
| [Benchmark](bench/README.md) | Monolith beside other PDSes, and how it's run |

## Layout

| Path | |
| --- | --- |
| `spec/` | The specification. `PDS.md` links a page for each area, and beside them are the specs it rests on (atproto's, the RFCs, WebAuthn, the spaces proposal, MCP's), the lexicons and the test vectors |
| `harness/` | Runs the server beside the reference and compares them: `compare.mjs` and its `checks/`, the upgrade run, `perf.mjs`, the benchmark, the compatibility check, the gates, `look.mjs` and the spaces run |
| `web/` | The OAuth authorization pages, a Svelte 5 app that `pds-server` embeds at compile time (`web/AGENTS.md`) |
| `crates/pds-repo` | The data model (DAG-CBOR, CIDs), the MST, signed commits and CAR files, with no I/O, checked by atproto's test vectors |
| `crates/pds-store` | The append-only log the server keeps its state in |
| `crates/pds-lexicon` | The lexicons as data: each method's arguments, and the MCP tool and CLI command made from it |
| `crates/pds-server` | The PDS: XRPC, the firehose, the MCP endpoint and OAuth. Each area's methods are a module of their own, named in `lib.rs`'s `AREAS` |
| `crates/pds-cli` | The CLI, a client of a running server |
| `crates/pds` | The one binary, `pds`. Its allocator is jemalloc, built by `.cargo/config.toml` to give freed memory back at once, so resident memory follows what's in use (`spec/STORE.md`, "Scale") |
| `Dockerfile` | The image ([Deploying](docs/guide/deploying.md)). `.knotless/image.sh` makes the released one from the same binary |
| `.changeset/`, `CHANGELOG.md`, `knope.toml` | Change files for the next release, what each version changed, and how `knope` makes a release ([Contributing](docs/guide/contributing.md#releases)) |
| `docs/` | The guides |
| `docs-site/` | The docs site, built with Astro from `docs/`, `spec/`, the lexicons, `compat/` and `bench/`. Its landing page's words follow `.claude/skills/landing` |
| `compat/`, `bench/` | The compatibility check's and the benchmark's pages and results |

The Rust is one flat workspace. Every crate sits one level down in
`crates/`, and the root `Cargo.toml` holds only the workspace, its shared
package fields and its dependencies' versions.

## Development

You need Rust through rustup and the Node version `.node-version` names.

```sh
(cd harness && npm ci) && (cd web && npm ci)
just dev --seed     # a server to try, with accounts in it
just quick          # a short harness run of each kind, while you work
```

A change goes spec first, then a harness check that fails, then the
server ([AGENTS.md](AGENTS.md#how-a-change-is-made)). `just gates` runs
everything on the runner when you push.
[Contributing](docs/guide/contributing.md) has the rest.

## Known gaps

- A server started from a backup doesn't handle the rollback. It numbers
  its firehose events again from the backup's last one, and doesn't tell
  any relay or AppView to sync its accounts again.
- There are no OAuth account pages (`/account`). An account lists and ends
  its OAuth sessions and devices with `pds oauth …` and the `oauth_` tools
  instead (`OAUTH-ACCOUNT.md`), and adds and removes passkeys with `pds
  passkey …` and the `passkey_` tools (`PASSKEYS.md`).
- Passkeys are ES256 or RS256, with only `none` attestation.
- There's no sign-up from the authorization page.
- The authorization page shows a `space:` permission as its scope string
  instead of describing it in words (`OAUTH-SCOPES.md`, "Spaces").
- The CLI and the MCP tools take only `Bearer` tokens, so an OAuth token
  can't be used through them (`OAUTH-SCOPES.md`).
- Permission sets are resolved through DNS, and the harness can't serve
  that to both sides. It checks them through `PDS_LEXICON_AUTHORITY_DID`,
  and the server's own tests check the DNS lookup.
- The server makes only `did:plc` accounts. A `did:web` account moves in
  with a service token its owner signs (`MIGRATION.md`).
- `resolveHandle` answers only its own accounts' handles, and doesn't ask
  anyone else.
- Of the sync methods, it serves `getRepo`, `getLatestCommit`,
  `subscribeRepos`, `listRepos`, `getRepoStatus`, `getBlocks`,
  `getRecord`, `getBlob` and `listBlobs`. It sends `requestCrawl` to its
  crawlers but doesn't serve it.
- No MCP tool uploads or reads blobs, or imports a repository.
  `upload-blob`, `get-blob` and `import-repo` are CLI commands only.
- MCP serves only tools. There are no resources, prompts or
  `subscriptions/listen`.
- Mail sent over SMTP (`EMAIL.md`) isn't an outbound request in the sense
  of `OPERATIONS.md`, so it has no span and no `pds_outbound_*` metrics.

## License

MIT or Apache-2.0, at your option: [`LICENSE-MIT`](LICENSE-MIT),
[`LICENSE-APACHE`](LICENSE-APACHE). The specs, lexicons and RFCs vendored
under `spec/` keep their own licenses, which sit beside them.