PDS account migration

Last Updated: 2026-06-10

Runbook for moving a Substratum login identity off pds.substratum.cloud to Bluesky, another hosted PDS, or self-hosted hardware. Applies when membership lapses, you choose self-hosting, or you want your repo on a different AT Protocol host.

In the app: Account → Move identity (/account/migrate).

Recommended tool: PDS MOOver

Substratum recommends PDS MOOver for cooperative migrations when both the source and destination PDS participate (including Substratum PDS → Bluesky or a home PDS).

Why MOOver	Detail
End-to-end	Exports your repo (CAR), re-uploads blobs, walks PLC identity cutover, and activation — the same phases in the AT Protocol account migration guide.
Community standard	Listed alongside official AT Protocol tooling; widely used for Bluesky and indie PDS moves.
Extras	Optional automated backups, missing blob repair, and Turn Off to deactivate the old PDS account after cutover.

Before you start: Read MOOver precautions & FAQ. Migration is sensitive and partly irreversible — use a desktop browser, have your verified email ready for the PLC token, and understand that MOOver is third-party software (not operated by Substratum).

What moves vs what Substratum handles separately

Asset	MOOver / AT migration	Substratum note
DID + handle	Yes	Same did:plc until PLC operation completes
AT Protocol repo (posts, likes, cloud.substratum.* records on PDS)	Yes (CAR + import)	Records must have synced to PDS first — resolve sync failures in the app
Media blobs on PDS	Yes	Re-uploaded after repo import
File bytes on private mesh / safety-net	No	Stay on Substratum storage until copied locally or policy expires — MOOver does not move mesh blocks
Gateway Postgres catalog	No	Drive tree converges from PDS records when catalog dual-write is complete; until then keep local/sidecar copies of important files

See ADR 29: Private PDS namespace and local CAR export for long-term export and vault plans.

Step-by-step (Substratum → new PDS)

1. Prepare on Substratum

• [ ] Open Account → Sync failures in the file explorer and retry or clear failed metadata jobs.
• [ ] Confirm important files exist on a local device or sidecar (mesh bytes are not part of MOOver).
• [ ] Note your current handle and ensure your account email is verified (needed for PLC signature email).

2. Choose destination PDS

Destination	New PDS URL (MOOver field)	Notes
Bluesky	https://bsky.social	Create a Bluesky account first if needed; use the same handle you want on bsky.social.
Another host	Provider’s PDS URL	Follow that host’s signup / invite instructions.
Self-hosted	Your home PDS URL (e.g. https://pds.example.com)	Follow the self-hosted troubleshooting runbook to install Substratum; use the PDS URL MOOver expects.

3. Run PDS MOOver

1. Go to pdsmoover.com/moover.
2. Old handle + password — your current Substratum PDS credentials.
3. New PDS URL, new email, new handle (and invite code if the host requires one).
4. Complete the flow; enter the PLC token from email when prompted.
5. Wait until MOOver reports migration complete and the new account is activated.

Protocol reference (manual / debugging): atproto.com/guides/account-migration.

4. Reconnect Substratum

1. In the file explorer: Account → Move identity → Sign out to reconnect.
2. Sign in with your handle on the new PDS (same DID, new host).
3. Substratum attaches OAuth and receipt sync to the new PDS.

5. Deactivate Substratum PDS (recommended)

Use MOOver Turn Off to deactivate the old account on Substratum PDS after you confirm drives and files look correct on the new host.

Lapsed membership

When Substratum Cloud sync and uploads are paused, you can still:

• Read existing cloud files (subject to policy),
• Clean up or delete cloud.substratum.* records on our PDS,
• Migrate your identity with MOOver to Bluesky or self-hosting.

Renewing membership is optional if you intend to leave Substratum PDS entirely.

Troubleshooting

Symptom	Likely cause	Action
Missing images after migration	Blobs not fully copied	MOOver Missing Blobs
Old PDS still “current” in some apps	Identity cache	Log out everywhere; wait up to ~24h on aggressive caches
PLC step stuck	Email token not entered	Re-open MOOver; check spam for PLC signature mail
Drives empty after reconnect	Catalog not on PDS yet	Ensure sync failures were cleared pre-migration; restore from local/sidecar copies
MOOver cannot reach Substratum PDS	PDS offline or account locked	Contact support if on paid Substratum login

Related

• Garage v1 rollout — entitlement lapse and Phase 2 alerts
• OAuth and PDS origins — sign-in after migration
• Self-hosted troubleshooting — home PDS + installer
• ADR 32: Account entitlements
• Bluesky advanced migration guide — Bluesky-specific UI path (alternative to MOOver)