PDS

Operating atproto-pds

A Personal Data Server in Rust: repository storage, federation, an OAuth 2.1 provider, permissioned spaces, and a mode for running behind an entryway. One storage engine, eighty environment variables, and a set of configurations that refuse to start on purpose.

§ 01

Status, stated plainly

That sentence is deliberately two claims. The README used to open with an all-caps plea not to use the crate yet, ten lines above “single-node deployable”, and left the reader to guess which was meant. They were about different things — the binary and the API — and now each is said once. The same sentence is in src/lib.rs word for word, and a test fails if the two stop matching or if the old banner comes back.

On the binary: every foundational subsystem has shipped end to end — storage dispatch, federation, admin endpoints, the OAuth provider, the Sync 1.1 protocol, identity, user-facing endpoints, account migration and operational hardening — and the deployment note is a real deployment’s runbook rather than a sketch. Every public read and write routes through the PublicRealmBackend trait. The Postgres accounts dispatch is finished; the Postgres cutover as a whole is not, and Postgres is not a deployment mode (§ 08). An earlier revision of the README said both were closed.

On the crate: its modules are pub so its own binaries and tests can reach them, and so atproto-entryway can reuse the portal chrome, the PAR checks and the scope describer. None of that is a stability promise.

§ 02

What it serves

Health checks live at GET /_alive, GET /_ready and GET /xrpc/_health, and GET / is a plain-text banner naming the host, the DID and the build. GET /_tls-check?domain= answers a reverse proxy’s on-demand TLS question (§ 06). Prometheus metrics are served on a listener of their own, never on the main one, when the metrics feature is built and PDS_METRICS_BIND is set. The crate README’s Routed surface lists every mounted path, and a test holds that list and the router to each other in both directions.

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.

Sign-up and sign-in are pages too (/account/signup, /account/signin), and the signup form names the handle domains this server issues under. Behind an entryway the sign-in, sign-up, credential and session pages redirect to the same path on the entryway, delegation and the migration wizard answer 404, and the repository browser and the spaces pages stay here, with the data (§ 11).

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

sqlite and http are features only because they are on by default; a build with --no-default-features has to list both, and the crate refuses at compile time without either. The binaries carry required-features = ["clap"], so cargo install --path crates/atproto-pds without --features clap,… installs nothing and says so only by its silence.

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, and does not print the value of a secret variable. What follows is every PDS_ variable the server reads except PDS_POSTGRES_URL, which exists only to be refused (§ 08), grouped by what they govern. Defaults are the ones in the source; where there is none, this page does not invent one.

PDS_BIND=0.0.0.0
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=true
PDS_TRUSTED_PROXY_HOPS=1
PDS_CRAWLERS=https://bsky.network
PDS_CRAWLER_ANNOUNCE_DELAY_SECS=15
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_EMAIL_SMTP_URL=smtp://user%40example.dev:…@smtp.example.dev:2525?tls=required
PDS_EMAIL_FROM_ADDRESS=noreply@example.dev
RUST_LOG=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

Three Dockerfiles ship a pds, and a fourth does not. The plain Dockerfile at the repository root builds the CLI tools and contains no server — deploying it and expecting one is the mistake the crate’s own deployment note exists to prevent.

docker build -t atproto-pds:deploy -f Dockerfile.pds \
  --build-arg PDS_FEATURES=clap,smtp,metrics,hickory-dns,object-storage \
  --build-arg BUILD_REV=$(git rev-parse --short=10 HEAD) .

Every stage of every image takes its feature list as PDS_FEATURES, and a test fails if any defaults to a set other than Dockerfile.pds’s. BUILD_REV is the commit the server names in /xrpc/_health, the GET / banner, its User-Agent and its startup log; .dockerignore strips .git, so without one all four say unknown. On Railway a GitHub-triggered deploy fills it in, and a railway up does not.

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. On SIGTERM or SIGINT the server cancels long-lived workers, lets in-flight requests finish and closes WebSocket subscribers cleanly, within PDS_SHUTDOWN_DEADLINE_SECS.

{
	on_demand_tls {
		ask http://localhost:3000/_tls-check
	}
}

pds.example.com, *.pds.example.com {
	tls {
		on_demand
	}
	reverse_proxy http://localhost:3000
}

/_tls-check?domain= gives the reference PDS’s answers — 200 for the server’s own hostname and for a held handle, 400 for a domain outside PDS_SERVICE_HANDLE_DOMAINS, 404 for an unheld handle — at a different path. A Caddyfile the reference installer wrote asks /tls-check and needs changing.

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: one container, one volume at /data, one replica, and overlapSeconds = 0 so the old container lets go of the volume before the new one mounts it. The platform specifics are Railway’s; the traps below are not, and most of them cost somebody an afternoon.

§ 08

Configurations 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. Several more configurations are real and ask for something the binary you built cannot do, or contradict each other. Every one of them fails at boot, naming the variable, 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. It tracks the 2026-10-01 spaces alpha.

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 and syncers 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. A credential is bound to its holder’s key with HTTP Message Signatures (RFC 9421), which replaced DPoP in the 2026-10-01 alpha.

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_DURABILITY_PROFILE=sql keeps it in the accounts database, and PDS_VALKEY_URL moves it to Valkey or Redis; both survive a restart.

Taking a credential back early

Short expiry is the primary mechanism — ten minutes by default, an hour at most. As a space authority this server also records every credential it issues and revokes, ahead of expiry, the ones a change means it would no longer issue: removeMember and putMember for that member’s, updateSpace for every one the new policy refuses, deleteSpace for all of them. A credential a managing app authorised is kept while the same app still decides. Revocations take effect here at once and go to every other repo host serving a writer in the space through notifyCredentialRevoked, a hundred jtis a call; a host receiving one refuses that credential with 401 CredentialRevoked until it would have lapsed anyway.

Telling members something changed

Writes do not push content. A syncer registers with registerNotify — an explicit, whole-space, expiring registration, named by its service identifier — and receives contentless notifyWrite events carrying the writer’s repoRev and the space’s sequence, then fetches for itself if it wants the data. The space host sequences its writers’ updates with a spaceRev, and a writer’s repo host delivers to a remote space host through a persisted, coalescing retry queue. Deletion is announced through notifySpaceDeleted.

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 once relied on the first alone and now perform the second: createRecord (the only space write that lacked it), and the sync reads now named getLatestCommit 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.

§ 10

Handing handles to Highport

Optional, off unless PDS_HIGHPORT_DOMAINS is set, and a change to who answers for the handles this server issues rather than to which handles it issues. Normally this server answers /.well-known/atproto-did for every name under a service domain. With a base delegated, the domain’s wildcard points at Highport instead, and Highport answers from a reservation row — so a name under the base resolves only if this server has reserved it there, for the right DID. What that buys is that one hostname is both a handle and somewhere its holder can publish a site.

The reserve at signup is inline, between the signed PLC genesis and its irreversible submission, so a refusal costs nothing and two concurrent signups for one name resolve to one winner. A rename reserves the new name inline and releases the old one afterwards. Everything else — takedowns, deletions, a handle adopted by refreshIdentity — is a spawned, best-effort call, logged on failure and never retried.

Before it releases anything, reconcile asks the DID document where the identity lives, and leaves alone a name whose DID is now hosted elsewhere; the account-state follow-ups ask the same question. The check needs PDS_DID_PLC_URL. Reservations younger than ten minutes are skipped so a signup in flight is not raced. atproto-pds-admin highport release --hostname clears a mismatch or foreign row by hand, printing who holds the name before it asks.

§ 11

Behind an entryway

A PDS can run as a member of a cluster behind an entryway — atproto-entryway, or Bluesky’s. It keeps the data side of its accounts: repositories, blobs and repository signing keys. It hands the account side to the entryway: credentials, sessions, OAuth, handles and PLC rotation. Setting PDS_ENTRYWAY_URL switches the mode on, and the four required settings are the reference PDS’s, so the same values configure either implementation; entryway keys show prints them. The entryway guide covers the other side.

Adopting a running server

Switching an existing PDS is a migration with a maintenance window, not a restart: its accounts’ sessions and OAuth grants stop working, and their passwords and DIDs have to reach the entryway first. With PDS_ENTRYWAY_ADOPTION=true, set for that window only, the server answers two admin routes.

# Every account, its password and app-password hashes, and the unused
# invite codes. Owner-readable only; delete it after the import.
atproto-pds-admin entryway export --out bundle.json
entryway accounts import bundle.json --dry-run

# Show, then sign and submit, the PLC update that lists the recovery key and
# the entryway's rotation key directly above this server's own.
atproto-pds-admin entryway adopt --entryway-key did:key:… --recovery-key did:key:…
atproto-pds-admin entryway adopt --entryway-key did:key:… --recovery-key did:key:… --apply

adopt refuses a DID that would pass PLC’s five rotation keys, listing them so you can choose one to drop, and leaves alone a DID that already lists both. Until this server’s own keys are removed from each DID, restoring its standalone settings is the way back. The full procedure is § 9 of the entryway deployment guide.

§ 12

Administration & tests

atproto-pds-admin is an ordinary HTTP client over the server’s admin XRPC, authenticated with the admin password against --base-url. It runs anywhere that can reach the server, which on a distroless deployment is the only way it runs at all. atproto-pds-admin <command> --help documents every flag.

The same operations are available over com.atproto.admin.*, and many through the HTML dashboard at GET /admin.

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

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

# Everything
cargo test --workspace --all-features

# 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 integration feature_postgres_live::