PDS

Operating atproto-pds

A Personal Data Server in Rust: repository storage, federation, an OAuth 2.1 provider, and permissioned spaces. Two storage profiles, fifty-two environment variables, and two documented modes 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-profile 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. The fjall public-realm sweep routes every public read and write 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.

§ 03

Storage profiles

Two backends for the per-actor store, mutually exclusive and chosen at compile time. This is a build decision, not a runtime one.

The cross-account accounts database is separate and independent of that choice. It is a single shared SQLite at PDS_DATA_DIRECTORY/accounts.sqlite, and it is the only supported accounts backend.

§ 04

Building

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

cargo build --no-default-features \
  --features clap,fjall,smtp,metrics,hickory-dns \
  --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.

§ 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

Two backends exist in the source tree, compile behind Cargo features, and have tests. They are deliberately not wired into the pds binary. They 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. Four variables govern delivery, and how far behind a member may fall before catching up stops being incremental:

§ 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 fjall storage-parity suite
cargo test -p atproto-pds --features http,clap,fjall

# 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