Keep your casts. Keep the media.
Farcaster Ark is a local-first command-line tool that creates repeatable, verifiable snapshots of a Farcaster account. It preserves signed protocol records, useful Neynar views, and downloadable media without sending archive contents anywhere other than the APIs and media hosts needed to retrieve them.
Farcaster Ark is an independent open-source project. It is not affiliated with or endorsed by Farcaster or Neynar.
- Authored casts and replies as raw, signed protocol messages.
- Likes, recasts, following, mentions, profile data, username proofs, verifications, storage limits, and on-chain account events.
- The current follower list and Neynar-enriched cast views in a full backup.
- Downloadable images, video, audio, and PDFs referenced by the profile or authored casts.
- A manifest with record and request counts, a known-minimum Neynar credit estimate, completeness notes, and SHA-256 checksums.
Each run creates an immutable timestamped snapshot. Media is content-addressed and deduplicated across snapshots, so unchanged files are stored once.
- macOS or Linux.
- Python 3.10 or newer.
- A Neynar API key.
- Enough local disk space for the account's media.
- Optional:
ffmpegfor HLS/DASH streaming video. Direct images, audio, video, and PDFs do not require it.
There are no required third-party Python packages.
Neynar requires an API key for its HTTP APIs. A free Neynar account is enough to get started, although a large account may require more credits than the free allowance provides.
- Open the Neynar Developer Portal and sign up or sign in.
- Create or select an app in the portal if prompted.
- Copy the app's API key. Neynar's API quickstart confirms that keys are obtained from the Developer Portal.
- Store only the key in a private file:
mkdir -p "$HOME/.config/farcaster-ark"
install -m 600 /dev/null "$HOME/.config/farcaster-ark/neynar-api-key"${EDITOR:-vi}"$HOME/.config/farcaster-ark/neynar-api-key"Farcaster Ark refuses a key file that is readable by other users. It also
accepts NEYNAR_API_KEY from the environment, but the private file is better
for unattended monthly backups. Never commit the key.
No Farcaster signer, seed phrase, private key, wallet connection, or Neynar app wallet is required. Farcaster Ark only performs read operations.
Clone or download this repository, then install it into an isolated virtual environment:
cd farcaster-ark
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
farcaster-ark --versionpipx install . is also supported if pipx is already installed. For a source
checkout without installation, use python3 -m farcaster_ark anywhere this
README uses farcaster-ark.
Pass a Farcaster username with or without its leading @:
farcaster-ark backup aliceThe default archive is ~/FarcasterArk. Choose another disk or directory with:
farcaster-ark backup alice --output /Volumes/Backup/FarcasterArkThe command resolves the username to its permanent FID and can optionally cross-check an expected FID:
farcaster-ark backup alice --fid 1234Progress is printed without printing the API key. A failed run remains clearly marked as an in-progress snapshot; it is never published as complete.
Farcaster Ark uses large raw-protocol pages and deduplicates media to reduce repeat work. The manifest records a known-minimum estimate, not a billing receipt: undocumented endpoints and failed/retried requests may add usage.
After one successful snapshot, estimate the next run without making API calls:
farcaster-ark estimateFor unattended runs, stop before API access if the previous snapshot projects more than a chosen budget:
farcaster-ark backup alice --credit-budget 5000For a cheaper signed-protocol snapshot, omit the enriched cast views and the v2 follower list:
farcaster-ark backup alice --protocol-only
farcaster-ark estimate --protocol-onlyThe full mode is the default because it preserves the broadest account view.
Verify the latest snapshot and every media blob it references:
farcaster-ark verifyVerify a named snapshot or a non-default archive:
farcaster-ark verify --snapshot 2026-07-14T033643Z \
--output /Volumes/Backup/FarcasterArkIf API collection completed but media downloading was interrupted, resume the newest complete staging snapshot without spending additional Neynar credits:
farcaster-ark resumeUse --skip-media when only protocol/API data is wanted. Use
--refresh-media to try every URL again even when its earlier download is
still present.
Running the same full command monthly creates a new snapshot and reuses media already stored in the archive.
Generate and install a job for 03:00 local time on the first day of each month:
farcaster-ark launchd alice --installThe command writes a per-account plist under ~/Library/LaunchAgents and
prints the launchctl bootstrap command needed to load it. Use --day,
--hour, --output, --api-key-file, --credit-budget, or
--protocol-only to change its settings. Run without --install to inspect
the plist on standard output first.
Find the absolute executable path with command -v farcaster-ark, then add a
monthly entry with crontab -e, for example:
031**/absolute/path/to/farcaster-ark backup alice >> "$HOME/farcaster-ark.log" 2>&1Scheduled jobs must be able to access the archive disk and API key file.
~/FarcasterArk/
├── LATEST
├── media/
│ ├── index.json
│ └── blobs/<sha-prefix>/<sha256>.<extension>
└── snapshots/<UTC timestamp>/
├── manifest.json
├── SHA256SUMS
├── media-manifest.jsonl
├── account/
├── protocol/
└── neynar/
Copy the entire archive directory when moving it. Snapshots refer to the shared
media/blobs directory.
This is a point-in-time account-state backup, not a private client-data export.
- Normal protocol
*ByFidqueries return current valid state. Content removed before the first backup generally cannot be reconstructed. Monthly snapshots preserve changes observed after the first run. - DMs, drafts, bookmarks, mutes, blocks, and other client-private state are not Farcaster protocol account messages and are not included.
- Replies authored by the account are included. Incoming mentions and current followers are included in a full run, but every reply or reaction made by other people on every cast is not expanded with costly per-cast crawling.
- Farcaster media lives at external URLs. Hosts may delete files, block
automated access, expire signed links, or disappear. Every attempted URL and
failure status is retained in
media-manifest.jsonl. - The archive contains public keys, wallet identifiers, and signed public messages, but never Farcaster private keys or wallet secrets.
The Neynar key is sent only in requests to Neynar API hosts; media hosts never
receive it. Media URLs and redirects resolving to localhost or private network
addresses are blocked by default. --allow-private-media-hosts disables that
protection and should be used only with trusted account data.
See SECURITY.md for reporting and storage guidance.
Run the local verification suite:
python3 -m unittest discover -s tests -v
python3 -m py_compile farcaster_ark/*.py bin/backup_farcaster.py
sh -n scripts/monthly-backup.shTests use mocked API and media responses and spend no Neynar credits. See CONTRIBUTING.md for contributor guidance.