FlockOff is an AT Protocol mass-block tool. Paste a post URL from an Atmosphere client or a raw at:// URI, see everyone who engaged with it (likes, reposts, quotes, replies, the OP), filter by relationship, and kick off a background batch block job — all written directly to your own PDS. No server-side database. Your block history lives in your AT Protocol repo, not ours.

→ flockoff.app

Features #

Fetch all engagement on any AT Protocol post
Filter by type (OP / Likes / Reposts / Quotes / Replies) and relationship (mutual / following / follower)
Background block jobs with live progress streaming (SSE)
Full undo / redo / resume support
Share a block event as a public AT Protocol block list
Re-check past events for new engagement and block new accounts
Import and manage AT Protocol block lists via the List Editor
All state stored in your own PDS as app.flockoff.blockEvent records

Tech Stack #

Framework: Next.js 16 (App Router)
Auth: AT Protocol OAuth (@atproto/oauth-client-node)
Session: iron-session v8 (encrypted cookie, no DB)
Styling: Tailwind CSS v4 + shadcn/ui (Base UI)
Deployment: Railway (Docker)

Running Locally #

Prerequisites #

Node.js v24+
An AT Protocol account on Bluesky or another PDS that supports the current granular OAuth repo: permissions

1. Clone and install #

git clone https://github.com/ajbirdd/flockoff.git
cd flockoff
npm ci

2. Set environment variables #

Create a .env.local file in the project root:

NEXT_PUBLIC_APP_URL=http://localhost:3000
SESSION_SECRET=any-random-string-at-least-32-chars-long

Note: OAUTH_PRIVATE_KEY is only required for production. In development, the app uses the AT Protocol loopback OAuth flow (public client — no key needed).

Login requests only the scopes needed for blocking. The first list action prompts for the additional list permissions through FlockOff's OAuth upgrade flow.

FlockOff does not fall back to the legacy transition:generic scope because it would grant write access to every record type in the user's repository. Older PDS installations must be updated before their accounts can use FlockOff.

3. Run the dev server #

npm run dev

Open http://localhost:3000 and sign in with your Atmosphere account.

Production Setup #

Generate an OAuth private key #

FlockOff uses a confidential AT Protocol OAuth client in production, which requires an ES256 private key. Generate one with Node.js:

node scripts/generate-key.mjs

Copy the printed OAUTH_PRIVATE_KEY='...' line into .env.local. Keep it secret and never commit it.

Required environment variables #

Variable	Description
`NEXT_PUBLIC_APP_URL`	Your production URL, e.g. `https://flockoff.app`
`OAUTH_PRIVATE_KEY`	ES256 JWK JSON string (see above)
`SESSION_SECRET`	Random string, 32+ characters
`BETA_LIST_URI`	Optional AT URI of an allowlist block/list record for limited beta access
`APPVIEW_URL`	Optional AppView base URL for reads; defaults to `https://public.api.bsky.app`

Deployment #

FlockOff is designed for Railway using a standalone Next.js Docker build. See context.md for the full Railway setup checklist.

Before deploying a changed lockfile, run npm audit --omit=dev and review upgrades deliberately. Do not use npm audit fix --force on this application.

Architecture Notes #

No database — all block event state lives in the user's own PDS as app.flockoff.blockEvent lexicon records.
In-memory job queue — block jobs run in RAM. Server restarts lose active jobs; the Resume button recovers from pendingDids stored in the PDS record.
OAuth session — encrypted iron-session cookie. No tokens or user data stored server-side beyond the in-flight session.

License #

MIT

Clone this repository

FlockOff #