pds.js

tangled.org git.pdsjs.dev

A single-account AT Protocol Personal Data Server written in JavaScript. Runs on Node.js, Deno, or Cloudflare Workers. Federates with the live network.

Work in progress. Experimental. Probably not production-ready yet, though the author's account, @chadtmiller.com, runs on it.

What makes this different from the official PDS

The official atproto PDS is a multi-tenant server built for running thousands of accounts. pds.js is built around a different premise: one server, one identity, yours.

It runs on the edge. The Cloudflare Workers build keeps repos in Durable Objects and blobs in R2. No VM, no persistent disk.
It serves one account. The server answers RepoNotFound for every other DID. Nothing in it models tenants, invite codes, or moderation of other people.
It hosts an account interface. Sign in at /account to see what each app has written to your repo, manage passkeys and app passwords, take a CAR backup, or rename your handle. You never touch a command line.

Labs features (experimental)

Each one is off by default. Configuration has the setting that turns each on. They are exempt from semver and may change shape or disappear in any release, including a patch.

A site platform. Lexicon records stored in your repo can power a public website served from your PDS. No separate hosting required.
Git repositories. Push to your PDS over git-remote-atproto, clone with stock git over read-only HTTP. Repos live as dev.pdsjs.git.repo records and chunked blobs in your repo.
A private file store. Drive is a blob-backed file manager built into the account interface. Upload files, get public /.blobs/<cid> links, stream video with seeking. Large files upload across multiple requests and land as a single blob.
Permissioned data. Private per-user repos shared through spaces, a draft proposal on top of atproto. Wire formats may change.

Quick start

$ git clone https://tangled.org/chadtmiller.com/pds.js
$ cd pds.js && pnpm install
$ just dev

The workspace uses the workspace:* protocol, so install with pnpm. just dev needs just and Docker. It starts a local PLC, relay, and Caddy, runs the PDS, and registers a mock account with a few records. Open localhost:2471/account and sign in with the printed credentials. just dev-down tears it all down.

Deploy

The fastest path is start.pdsjs.dev, a browser wizard that deploys to your own Cloudflare account. It generates your signing key and secrets client-side. Nothing sensitive leaves your tab.

For manual deployments:

Target	Guide
Docker	deploy-docker.md
Node.js	deploy-node.md
Cloudflare Workers	deploy-cloudflare.md
Deno	deploy-deno.md

Every deployment needs TLS in front of it, a public hostname, and one run of npm run setup to register the DID with the PLC directory.

The account interface

Your apps groups the repo by the application that wrote it. Each row shows its sessions and a write history.
Sign-in and security holds passkeys, active logins, app passwords, the recovery address, and a kill switch that pauses the account.
Drive is a private file store backed by blobs. Public files get a /.blobs/<cid> link you can use anywhere an image or video URL works.
Sites manages installable web apps served from your repo. Anyone who visits your PDS origin sees the site.

Example apps

Four working apps live in examples/apps/. Each one discovers whose repo it serves from its own origin, so any of them runs on any pds.js account that installs it.

App	What it does
`photos.mjs`	Photo galleries from `social.grain.*` records. Justified layouts, lightbox, map, terrain headers, network favourite counts
`roasts.mjs`	Coffee roast log with a live timer, weight-loss and development metrics against a Sweet Maria's roast card, notes and photos
`drop.mjs`	Image host. Drag, paste, or pick a file and the public `/.blobs/<cid>` URL copies itself
`videos.mjs`	Video gallery from Drive. Plays same-origin with seeking, read-only; uploads happen in Drive

$ pdsjs-site install at://you.example.com/dev.pdsjs.app.manifest/photos

What it implements

pds.js covers the com.atproto.repo.*, com.atproto.sync.*, com.atproto.server.*, and com.atproto.identity.* namespaces. That includes record writes, the firehose over subscribeRepos, streaming blob upload and ranged download, handle resolution and rename, and account migration in and out. It signs commits with a did:plc identity and proxies app.bsky.* to an AppView with service auth.

Sessions come from passwords, app passwords, passkeys, or OAuth 2.0 with PKCE and DPoP-bound tokens.

There are no com.atproto.admin.* endpoints and no invite codes. A single-account server has nobody to administer. The endpoint comparison lists every endpoint on both sides.

Documentation

Document	Contents
Configuration	Every environment variable
Architecture	Ports, adapters, packages, library usage
Building an app	Sites, manifests, installs, how to update
Permissioned data	Spaces proposal, the run club example
Endpoint comparison	Coverage against the official atproto PDS
Scope comparison	OAuth scopes against the reference implementation
Contributing	Local dev setup, tests, commit gate

Source at tangled.org/chadtmiller.com/pds.js. Packages on npm under @pdsjs. MIT licensed.

This page is a record in an atproto repo, served by the pds.js instance that holds it. The mark follows the unofficial JavaScript logo by Chris Williams, which is public domain.

connecting to pds.pdsjs.dev