PDS

Operating atproto-pds

A Personal Data Server in Rust: repository storage, federation, an OAuth 2.1 provider, and permissioned spaces. Two storage profiles, sixty-two environment variables, and three configurations that refuse to start on purpose.

§ 01

Status, stated plainly

Both that warning and the paragraph under it are true, which is the thing to understand before you decide anything. The server is single-node deployable for federated public traffic. Every foundational subsystem has shipped end to end: storage dispatch, federation gaps, admin endpoints, the OAuth provider, the Sync 1.1 protocol, identity gaps, user-facing endpoints, account migration, and operational hardening. Both heavy storage-layer batches are closed. Every public read and write routes through the PublicRealmBackend trait, and the Postgres accounts cutover routes every accounts-DB call through a runtime-dispatch AccountPool.

What that adds up to: a server that works, under CI gates, and has not yet accumulated the operational history that would justify putting somebody else’s account on it.

§ 02

What it serves

Health checks live at GET /_alive, GET /_ready and GET /xrpc/_health. Prometheus metrics appear at GET /metrics when the metrics feature is compiled in.

The account portal

Not every surface is XRPC. Before the portal, a PDS could be operated but not used without a client application: no way to sign in to the server itself, no way to change an email address or password, no way to see which app passwords and OAuth grants were outstanding or to end them. Pointing a browser at the host produced an empty 404. The portal is what an account holder can do with only a browser, and it is server-rendered HTML with no JavaScript at all.

The session is server-side rather than a JWT, and deliberately: the portal is the page that revokes credentials, so its own credential has to be revocable in the same breath. A stateless cookie that outlived “sign out everywhere” would be the one thing that button could not reach.

§ 03

Storage

One store for repositories, and an optional second place for blob bytes. The per-actor store is SQLite and is not a build decision any more; where blobs live is a runtime one.

§ 04

Building

cargo build --features clap,smtp,metrics,hickory-dns \
  --bin pds --bin atproto-pds-admin

cargo build --features clap,object-storage,smtp,metrics \
  --bin pds --bin atproto-pds-admin

PDS_DATA_DIRECTORY=./.pds-data \
PDS_SERVICE_DID=did:web:pds.example.com \
PDS_JWT_SECRET=$(openssl rand -hex 32) \
PDS_ADMIN_PASSWORD=$(openssl rand -hex 16) \
  cargo run --features clap,smtp,metrics,hickory-dns --bin pds

§ 05

Configuration

Configuration is environment plus flags; pds --help is authoritative. What follows is the full set of PDS_ variables the server reads, grouped by what they govern. Where a default is documented in the crate it is given; where it is not, this page does not guess.

PDS_BIND=0.0.0.0
PDS_PORT=3000
PDS_DATA_DIRECTORY=/var/lib/pds
PDS_PRODUCTION=true
PDS_SERVICE_DID=did:web:pds1.example.dev
PDS_HOSTNAME=pds1.example.dev
PDS_DID_PLC_URL=plc.directory
PDS_DURABILITY_PROFILE=sql
PDS_INVITE_REQUIRED=false
PDS_CRAWLERS=https://bsky.network
PDS_BSKY_APP_VIEW_DID=did:web:api.bsky.app
PDS_BSKY_APP_VIEW_URL=https://api.bsky.app
PDS_SERVICE_HANDLE_DOMAINS=.pds1.example.dev,.example.dev
PDS_SPACE_CREDENTIAL_TTL_SECONDS=7200
PDS_NOTIFIER_INTERVAL_SECS=5
PDS_ADMIN_BASE_URL=http://127.0.0.1:3000
RUST_LOG=info,atproto_pds=info

# PDS_JWT_SECRET, PDS_ADMIN_PASSWORD, PDS_OAUTH_KEYS_JWK_SET and the
# PLC rotation key come from your secret store, not from this file.

§ 06

Running it

Two Dockerfiles sit at the repository root and they build different things. Dockerfile.pds builds the server. The plain Dockerfile builds the CLI tools and does not contain a PDS — deploying that one and expecting a server is the mistake the crate’s own deployment note exists to prevent.

docker build -t atproto-pds:dev -f Dockerfile.pds .

The image runs as non-root, and everything durable — the accounts database, each actor’s own store, blobs, the key store — lives under PDS_DATA_DIRECTORY. There is no second service to run and no external database to provision.

Front it with a reverse proxy that terminates TLS, permits request bodies at least as large as your configured ceilings, and passes WebSocket upgrades through for subscribeRepos. Shutdown is coordinated: on SIGTERM or SIGINT the server cancels long-lived workers, lets in-flight requests finish, and closes WebSocket subscribers cleanly, so a rolling restart drains rather than severs.

What the server does to protect itself

Four things sit outside the handlers, and an operator sees all of them in the logs before they see them anywhere else.

§ 07

Deploying on a platform

The workspace carries railway.toml and a deployment note written against a real Railway deployment. The platform specifics are Railway’s; the traps below are not, and most of them cost somebody an afternoon.

§ 08

Modes that refuse to start

One backend exists in the source tree, compiles behind a Cargo feature, and has tests, but is deliberately not wired into the pds binary. Two further configurations are real and ask for something the binary you built cannot do. All three are documented here so nobody finds out the hard way.

§ 09

Spaces

This is the second PDS implementation anywhere to serve permissioned data spaces, and the first in Rust. That makes it useful in a way its maturity does not otherwise justify: interoperability work on the 0016 Permissioned Data draft needs a second implementation to test against, and this is it.

A public repository is public by construction — the MST leaks its key set even to a reader who cannot decrypt the records. A space is the permissioned alternative: membership gates reads, and the commit structure is built so a leaked commit does not become evidence of what it contained. The concept page covers the primitives; this section is what the server actually exposes.

Two namespaces

The split matters. simplespace is the owner’s control plane — who exists, who is a member. space is the data plane, and it is the one members talk to.

Getting in: the two-step exchange

A member does not authenticate to a space with their ordinary session. They exchange it. getDelegationToken issues a delegation token, and getSpaceCredential trades that for a short-lived space credential — both JWTs, defined in atproto-space as DelegationToken and SpaceCredential.

The exchange is replay-protected by a JTI guard. In its default form that guard is in-memory, which means it is per-process and it forgets on restart. Setting PDS_VALKEY_URL moves it to Valkey or Redis, where it survives both.

Telling members something changed

Writes do not push content. A recipient registers with registerNotify and then receives contentless notifyWrite events — just { space, repo, rev } — and fetches for itself if it wants the data. Deletion is announced the same way through notifySpaceDeleted.

Outbound delivery is retried with backoff and has a dead-letter queue behind it. Five variables govern delivery, and how far behind a member may fall before catching up stops being incremental:

Membership is the check that matters

A space endpoint has two gates and they answer different questions. Scope authorisation asks what an OAuth token is permitted to do — and returns early for anything that is not OAuth, because an app-password session carries no scopes and is full-authority over its own account. Membership asks whether this caller belongs to this space at all. Only the second one is about the space.

Three paths were relying on the first alone and now perform the second: createRecord (the only space write that lacked it, while putRecord, deleteRecord and applyWrites all had it), and the sync reads getRepoState and listRepoOps. If you are implementing the other side of this protocol, it is worth checking which of your own endpoints assert membership rather than merely authenticating.

notifySpaceDeleted had a related problem in its audience binding: the handler took aud from the unverified payload and handed it back as the expected audience, comparing a claim against itself. The audience is now decided from verified claims.

§ 10

Administration & tests

atproto-pds-admin covers invite-code issuance, account inspection, takedown and the rest of the operational surface; the same operations are available over com.atproto.admin.* and through the HTML dashboard at GET /admin.

# Default profile — SQLite, http, clap
cargo test -p atproto-pds --features http,clap

# Adds the object-storage suite
cargo test -p atproto-pds --features http,clap,object-storage

# Postgres accounts adapter (see § 08 before you rely on it)
cargo test -p atproto-pds --features http,clap,postgres

# Live Postgres round-trip; skips and reports OK when the DSN is unset
PDS_POSTGRES_TEST_URL=postgres://pds:pds@127.0.0.1:5432/pds_live \
  cargo test -p atproto-pds --features postgres-live-tests \
    --test feature_postgres_live