Bring your digital life to Oxy. The user taps Connect, signs in to the old
platform once (to prove the account is theirs), and Move brings over the
profile and follow list to Oxy and the posts to Mention — on web, iOS and
Android, at move.oxy.so (API api.move.oxy.so).
F1 platforms: Mastodon (and any ActivityPub server) and Bluesky. Threads,
Instagram, X, Medium and Substack are listed as "soon" (GET /platforms).
| Where | Owns |
|---|---|
| Oxy | The account, the linked external accounts (proof of ownership), the alsoKnownAs alias, the profile, follows, blocks, files, notifications |
| Mention | The imported posts: post_imports (origin, dedup, undo), the "originally posted on" badge |
| Move | ONLY migration state: jobs, cursors, and the source → destination map |
Move never holds a third-party token (Oxy's OAuth proves ownership and discards it). Mastodon and Bluesky content is read from public endpoints.
Oxy accepts profile, follow and block writes only from the user's own
session, so the Move client applies them. The backend builds the plan
(profile fields with media already imported into the user's Oxy files; follows —
and, for Bluesky, blocks — resolved to Oxy user ids in batches of 200) and the
client acknowledges what it applied (POST /jobs/:id/plan/ack). BEFORE each
write the client also acks the fact undo needs — the profile values it is about
to overwrite, which targets it already follows or blocks — and Move keeps the
first value of each fact (migration_jobs.undo_facts). So a migration resumes,
and undoes, from any device. Content is written by the backend to Mention
with Move's attested workload and the job's original requester proof.
packages/
frontend/ Expo Router + Bloom + @oxy.so/services: home, connect, confirm, progress, history
shared-types/ API types shared by both sides (job view, plan, platforms)
backend/ Express + Socket.IO + PostgreSQL (drizzle via @oxy.so/db) + BullMQ
src/sources/ one reader per platform: profile(), graph(), items() — resumable cursors
mastodon.ts ActivityPub actor/outbox/following (REST lookup fallback)
bluesky.ts public AppView XRPC; media = original blobs from the PDS
http.ts SSRF-safe JSON GET + per-platform backoff
src/destinations/
mention.ts product SDK transport; shared Mention contract
oxy.ts linked-account check, identity resolution, notification
media.ts Oxy imports media by URL, behind ONE fleet-wide limiter
src/pipeline/ runner (phases, checkpoints, deferral, pause), job service
src/queue/ BullMQ queue `migration` (low concurrency) + the stalled-job sweep
src/runtime/ composition, graceful shutdown, socket progress
src/connectors/ pure ActivityPub/atproto pieces copied from Mention
POST /jobsverifies the linked account with Oxy (GET /linked-accounts/by-user/:userId) and inserts the job (at most one active job per user and platform — a partial unique index). It is enqueued onmigration.- The worker re-verifies ownership, then runs profile → graph → content. A finished phase is never re-run; each phase checkpoints its source cursor.
- Content reads newest first, has Oxy import media into the user's files
(
docs/oxy-files.md), and sends batches of ≤ 50 to Mention. A self-reply or self-quote whose parent is not delivered yet is storeddeferredand re-sent at the end, oldest first. Replies to other people and boosts are skipped by default (includeRepliesToOthers,includeBoosts). - A rate limit anywhere (source 429, Oxy's ~30 imports/min/app media budget, Mention 429) pauses the job and re-enqueues it for later — never fails it. Transient errors retry with backoff from the last checkpoint. A job that lost its worker or its message is re-enqueued by a sweep that BullMQ schedules once per interval across the fleet (no leader election).
- Progress is pushed to the user over Socket.IO (
migration:progresstouser:<id>) and readable atGET /jobs/:id. On completion Move creates an Oxy notification of typesystem(entityType: app,entityId= the job id). - Undo (
DELETE /jobs/:id) deletes Mention's batch (DELETE /imports/v1/batches/:jobId) and returns the plan, the ack and the undo facts, so the client — on any device — unfollows and unblocks only what Move added and restores the profile.
| Method | Path | |
|---|---|---|
| GET | /platforms |
Available and upcoming platforms |
| POST | /jobs |
{ platform, linkedAccountId, options?, dryRun? } — dryRun returns the preview (profile, counts, date range) |
| GET | /jobs |
The user's migrations, newest first |
| GET | /jobs/:id |
One job (status, phases, counters) |
| GET | /jobs/:id/plan |
{ plan, ack, undoFacts }: profile, follow and block batches for the client (batches only once the graph phase has finished) |
| POST | /jobs/:id/plan/ack |
{ profileApplied?, followBatchesApplied?, blockBatchesApplied?, profileBefore?, alreadyFollowing?, alreadyBlocked? } (facts: first write wins) |
| POST | /jobs/:id/cancel |
Stop an active job |
| DELETE | /jobs/:id |
Undo |
GET /health (liveness) and GET /ready (Postgres + every shipped migration
applied) are unauthenticated; the ALB probes /ready.
All parsed in packages/backend/src/config.ts; see packages/backend/.env.example.
| Variable | Production source | |
|---|---|---|
DATABASE_URL |
SSM /oxy/move/DATABASE_URL |
Required |
REDIS_URL |
SSM /oxy/_shared/REDIS_URL |
Queue, media-import limiter (optional locally) |
OXY_API_URL |
task env | default https://api.oxy.so |
MENTION_API_URL |
task env | default https://api.mention.earth |
MEDIA_UPLOADS_PER_MINUTE |
default 30 | Oxy's per-app media import/upload budget |
EXPO_PUBLIC_OXY_CLIENT_ID, EXPO_PUBLIC_API_URL |
GitHub vars |
Frontend build |
SSM is the only copy of a production secret: set or rotate one with
aws ssm put-parameter --type SecureString --overwrite (oxy-infra runbook 46),
then force a new deployment. GitHub holds no runtime secret and the deploy
writes none (scripts/check-workflow-secrets.mjs).
bun install
docker compose -f docker-compose.postgres.yml up -d postgres
cp packages/backend/.env.example packages/backend/.env
bun run db:migrate --target-database=oxymove_dev
bun run dev:backend
bun run dev:frontendbun run check # AGENTS.md budget, gates (+ self-tests), typecheck, build
bun run lint # Biome (format + lint) + the frontend's Expo-only ESLint rules
bun run format # apply Biome formatting
TEST_DATABASE_URL=postgres://… bun run test # sources on recorded fixtures + pipeline on real PostgresSchema changes: edit packages/backend/src/db/schema/, bun run db:generate,
then add -- oxy:deploy-phase=pre|post as the first line of the new .sql
(scripts/check-migration-phase-markers.mjs fails CI without it).
- Backend —
.github/workflows/deploy-aws.ymlafter CI passes onmain: digest-pinned arm64 image, a task revision derived from the running one,--phase=premigrations before the rollout,--phase=postafter it, smoke checks, rollback on failure (.github/scripts/deploy-ecs-image.sh, from Mention). AWS side: oxy-infraterraform-uswest2/app-move.tfandiam-move-deploy.tf. - Web —
.github/workflows/deploy-frontends.yml:expo export, thenbunx wrangler@4 deployto an assets-only Worker onmove.oxy.so(workers_dev = false;public/_headerssetsnosniff+Referrer-Policy). - Native — bundle id / package
so.oxy.move(so.oxy.move.devwithAPP_VARIANT=development), schemeoxymove..github/workflows/android-release.ymlcalls oxy's reusable release on Oxy's build machine: a signed AAB + APK as the GitHub releaseandroid-v<version>, built only when thatversionhas none (the build number is derived from it)..github/workflows/publish-update.ymlpublishes the OTA update (oxy-ship, GitHub trusted publishing, no secret; do not rename the file) to channelproduction. A native change is aversionbump; JS-only changes ship as OTA. Both read the build env frompackages/frontend/eas.json'sproductionprofile.
Move uses the shared AWS workload provider and Oxy core transport. Configure the registered role and environment; local development may use a temporary assumed role or SSO provider. No Oxy API key pair, scope list or app consent is needed.
Each migration persists a durable Oxy task created from the real requesting session. Private linked-account reads, media imports and Mention calls use that same task and account. Cancel revokes it; undo creates a fresh short instruction from the current session, retaining the original batch. History, cursors and partial results remain intact if authority is revoked. Details and deployment order: first-party platform migration.
Move reads a Mastodon account's PUBLIC ActivityPub surface: the actor, the
outbox and following. It holds no key and no token.
- Unsigned first. Measured 2026-09-25: mastodon.social and hachyderm.io refuse the unsigned actor (401) but serve the collections unsigned.
- Then signed by Oxy. A 401/403 is retried once with an HTTP signature from
Oxy's instance actor (
https://oxy.so/ap/users/instance), which Oxy makes for Move throughPOST /federation/instance-fetch/sign(GET only, the instance key only, public https only; Oxy'sdocs/identity/instance-fetch.md). Every redirect hop is signed again. Once a COLLECTION of a host needed a signature (authorized-fetch mode), the rest of that job signs its reads of the host straight away; a refused actor alone does not switch it. - A signed refusal fails the job with
source-requires-authorized-fetch(the preview answers HTTP 422): the server blocks oxy.so, or federates only with an allow-list. Without a signed actor document Move still falls back to Mastodon's public REST lookup (/api/v1/accounts/lookup) for the profile. - Oxy's 429 on signing (1200 signatures a minute for the app) pauses the job like a source 429.
- Mastodon blocks are not moved. Mastodon's block list (
GET /api/v1/blocks) needs the user's own token, and Oxy discards the token its OAuth received, so Move cannot read it. Bluesky blocks are public repo records (app.bsky.graph.blockviacom.atproto.repo.listRecordson the user's PDS) and are moved; without a resolvable PDS they are skipped. - Unlisted posts import as public. Mention has no unlisted visibility for
imports (
public|followers_only); Mention's own ActivityPub ingest makes the same choice. Followers-only posts are not in the public outbox and are never read. - Audio attachments are dropped before import (Mention imports images, GIFs and video).
- Profile banners are not moved: an Oxy profile has an avatar and no banner.
- Replies whose target never arrives (a reply to a post that was filtered, deleted at the source, or is not the user's) import as standalone posts with a link to the original target, so nothing stays deferred forever.
Source of truth: Mention docs/import.mdx; Move's mirror is
packages/backend/src/destinations/mentionContract.ts and
src/__tests__/mention.contract.test.ts parses responses copied from Mention's
tests and checks every request against a copy of Mention's request schema.
POST /imports/v1/posts:batch— ≤ 50 items AND ≤ 1 MB body (the client splits by both). Per item:created|existing|deferred(parent_not_imported/quote_not_imported: nothing written) |failed. Adeferreditem is stored with its payload and resent once its target is delivered; at the end, targets Mention already holds from an EARLIER job are kept (checked with lookup), the rest are dropped for a link.- Media are
{ assetId, alt }— Oxy file ids Oxy imported as the user's media. Each import is recorded onmigration_items.media_assetsbefore the batch is sent, so a retry after a crash reuses it instead of importing again. Mention, not Move, references the files it uses (docs/oxy-files.md). DELETE /imports/v1/batches/:jobId→{ deleted, failed }.failed > 0is shown on the job (undo) and leaves it retryable.GET /imports/v1/lookup?platform=&sourceIds=…(≤ 200) →{ imported, federated }; Move readsimported.