ahetzm/cirrus
Watch
1
0
Fork
You've already forked cirrus
 0
mirror of https://github.com/ascorbic/cirrus.git synced 2026-10-02 14:51:48 +00:00
Code Issues Projects Releases Packages Wiki Activity
A single-user ATProto PDS that runs on a Cloudflare Worker https://cirrus.earth/
215 commits 15 branches 60 tags 5.4 MiB
  • TypeScript 96.8%
  • JavaScript 1.7%
  • HTML 1.4%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Matt Kane e6703d513c
 fix(create-pds): export Space Durable Objects from template worker (#248) 
The scaffolded wrangler.jsonc declares SpaceDurableObject and
SpaceIndexDurableObject bindings and migrations, but the worker entry
only re-exported AccountDurableObject. Wrangler rejects the deploy with
error 10070 because the migration names a class the script does not
export. The template entry now matches demos/pds.

Closes #246
2026-09-14 06:25:00 +00:00
.changeset fix(create-pds): export Space Durable Objects from template worker (#248) 2026-09-14 06:25:00 +00:00
.github/workflows feat(space-conformance): core check model, runner and computed coverage (#230) 2026-08-31 07:14:18 +01:00
apps/check fix(space-conformance): publish resolvable probe lexicons (#238) 2026-09-01 10:56:56 +01:00
demos/pds feat(demo): enable atproto spaces on the demo PDS (#222) 2026-08-29 16:45:17 +01:00
docs docs: add atproto spaces concepts and enable guide (#221) 2026-08-29 16:39:00 +01:00
packages fix(create-pds): export Space Durable Objects from template worker (#248) 2026-09-14 06:25:00 +00:00
plans fix(oauth-provider): resolve space type declarations with proof intact (#239) 2026-09-01 10:39:01 +00:00
.gitignore fix(pds): match reference PDS RecordNotFound message string (#190) 2026-05-25 08:47:45 +00:00
.prettierignore feat(pds): make pds into a library and add a cli (#18) 2025-12-28 17:11:53 +00:00
.prettierrc Initial commit 2025-12-26 11:34:54 +00:00
AGENTS.md Initial commit 2025-12-26 11:34:54 +00:00
CLAUDE.md refactor: switch to atcute libraries where possible (#65) 2026-01-04 13:24:45 +00:00
knip.json feat(check): browser spaces-conformance adapter (runner #3) (#234) 2026-08-31 07:14:19 +01:00
package.json ci: upgrade to pnpm 11 (#218) 2026-08-29 08:51:07 +01:00
pnpm-lock.yaml fix(oauth-provider): resolve space type declarations with proof intact (#239) 2026-09-01 10:39:01 +00:00
pnpm-workspace.yaml test(space-conformance): reference PDS matrix (calibration) (#236) 2026-08-31 07:14:20 +01:00
README.md Include package name in healthcheck version (#129) 2026-02-15 20:31:53 +00:00
renovate.json feat(oauth-provider): parse and grant space: scopes behind a flag (#209) 2026-08-29 10:23:44 +01:00
tsconfig.json Initial commit 2025-12-26 11:34:54 +00:00

README.md

☁️

CIRRUS

The lightest PDS in the Atmosphere

A single-user AT Protocol Personal Data Server (PDS) that runs on a Cloudflare Worker.

Why run your own PDS?

A PDS is where Bluesky data lives – posts, follows, profile, and media. Running a personal PDS provides:

  • Independence from platform changes – If Bluesky's ownership or policies change, the account remains under full control. No billionaire can take it away.
  • Network resilience – A diverse ecosystem of PDS providers makes the AT Protocol network stronger. More independent servers mean no single point of failure.
  • Data sovereignty – The repository lives on infrastructure under direct control
  • Portability – Move between hosting providers without losing followers or identity

Architecture

This implementation uses Cloudflare Workers with Durable Objects and R2:

  • Worker – Stateless edge handler for routing, authentication, and DID document serving
  • Durable Object – Single-instance SQLite storage for your AT Protocol repository
  • R2 – Object storage for blobs (images, videos)

The result is a PDS that runs at the edge with no servers to manage, automatic scaling, and pay-per-use pricing.

Quick Start

npm create pds

This scaffolds a new project, installs dependencies, and runs the setup wizard. See the PDS package documentation for detailed setup and configuration.

Before You Get Started

Before running your PDS, you'll need:

  1. A Cloudflare account – Sign up at cloudflare.com if you don't have one
  2. Your domain added to Cloudflare – Add the domain you plan to use for your PDS to your Cloudflare account:
    • Log into the Cloudflare dashboard
    • Click "Add a site" and enter your domain
    • Follow the instructions to update your domain's nameservers to point to Cloudflare
    • Wait for DNS propagation (usually a few minutes, can take up to 24 hours)

Once your domain is active in Cloudflare, you can proceed with the setup wizard.

Packages

Package Description
@getcirrus/pds The PDS implementation – handles repository operations, federation, OAuth, and the CLI
@getcirrus/oauth-provider OAuth 2.1 provider for "Login with Bluesky"
create-pds Scaffolding CLI to create new PDS projects

Status

⚠️ This is experimental beta software under active development. While the core features are functional and account migration has been tested, this PDS implementation is still being refined. Breaking changes may occur, and not all edge cases have been discovered. Consider backing up important data before migrating a primary account.

Core features currently working:

  • Repository operations (create, read, update, delete records)
  • Federation (sync, firehose, blob storage)
  • OAuth 2.1 provider (PKCE, DPoP, PAR)
  • Account migration from existing PDS (tested and verified)
  • Account migration to another PDS (stateless token generation)
  • Passkey authentication for passwordless login

See the PDS documentation for current limitations and roadmap.

Key Safety

Your signing key controls your identity. Cloudflare secrets cannot be retrieved after they're set, so backing up your key during setup is critical.

During Setup

When you run pds init, you'll be prompted to back up your signing key. Store it somewhere safe – a password manager, encrypted backup, or similar.

Key Recovery

If you've cloned to a new machine and see the "Key Recovery Required" error:

  1. Restore from backup – If you backed up your key (recommended), add it to .dev.vars: 
    SIGNING_KEY=your-backed-up-key-here
  2. Run init again – pds init will detect the local key and continue

If You've Lost Your Key

For did:web users:

  • Generate a new key by clearing .dev.vars and re-running pds init
  • Old signatures become unverifiable – followers may see warnings
  • Your identity continues, but there's no cryptographic proof of continuity

For did:plc users:

  • If you have a recovery key registered with PLC, you can rotate to a new signing key
  • Without a recovery key, you'll need to start a new identity
  • See the AT Protocol PLC documentation for recovery operations

Requirements

  • Cloudflare account with R2 enabled
  • A domain you control (for your handle and DID)

Resources

License

MIT. © Matt Kane (@ascorbic)