farcaster-in-three
v0.1.25
Published
A three-command tutorial for running your own Farcaster Snapchain node and client.
Maintainers
Readme
In Three
A three-command developer tutorial for running a Snapchain node and browser client from your own machine. Reads and writes go through your node, with no hosted Farcaster data API.
Website | Live proof | 中文教程 | npm | Docker | Source
The website includes a captioned 59-second walkthrough after the three-command quickstart.
What you need
- a fresh Ubuntu or Debian operator machine; the install below can add Docker
- an Ubuntu node machine with 4 CPU cores, 16 GB RAM, 2 TB free, SSH, and passwordless
sudo - up to a day for the first sync
On macOS, install Docker Desktop first. If Docker is already available, the installer leaves it alone. npm and Node.js are not required for this path.
Use a machine you already own. Add --hetzner if you want In Three to create one.
You do not need a Farcaster account. It is handled in step 3.
- Create a Hetzner account and an empty project.
- In the project, open Security → API tokens. Generate a Read & Write token and copy it.
- On your account's Limits page, choose Request change → Limit increase. Request at least 2,048 GiB of total Volume storage.
- Run
./in-three-container provision --hetznerand paste the token when asked.
Hetzner reviews quota increases manually. See its official API-token guide and quota guide.
Install
mkdir in-three-node && cd in-three-node
curl -fsSLO https://raw.githubusercontent.com/P-U-C/farcaster-in-three/v0.1.25/in-three-container
chmod +x in-three-container
./in-three-container doctor --install-dockerOn fresh Ubuntu or Debian, the last line installs and starts Docker. It does not install npm. Continue when the final line says All checks passed.
Run the three
./in-three-container provision
./in-three-container node up
./in-three-container client create- Machine: enter the SSH address of a machine you own. Use
./in-three-container provision --hetznerinstead to create one. - Snapchain: starts your node. Leave it running during the first sync.
- Client: creates a test account or connects an existing one, then opens your client.
Keep the in-three-node folder. If setup pauses, rerun the same command from that folder.
For a scripted owned-machine setup, place a dedicated key in the working folder:
cp ~/.ssh/id_ed25519 ./node-key
./in-three-container provision --host [email protected] --ssh-key /work/node-keyAdd --domain client.example.com when the SSH host is not the public client hostname.
Step 3 handles the Farcaster account
Choose CREATE, pick a password, and follow the funding prompt. In Three encrypts the new recovery phrase locally and sends only a revocable app key to the server.
Use a new test account. Never import a wallet that holds value.
When setup finishes, open the printed HTTPS URL and publish a test cast.
Useful commands
./in-three-container node status
./in-three-container client status
./in-three-container proof
./in-three-container destroynode status checks all three shards. If it prints RECOVERY REQUIRED, run the exact ./in-three-container node recover --shard N command it shows. The recovery keeps healthy shards and verifies a fresh snapshot before a brief restart.
On Hetzner, destroy deletes the server and volume. On a machine you own, it stops In Three and keeps the machine and its data.
Prefer npm?
If Node.js 22+ and npm are already installed:
npm install --global farcaster-in-three
mkdir in-three-node && cd in-three-node
in-three doctorRun the same three commands with in-three instead of ./in-three-container.
Help
- Operations: sync, recovery, upgrades, and teardown
- Security: keys and recovery files
- Architecture: read and write paths
- Proof: run receipts
- Agent runbook: guarded setup for coding agents
- All documentation
Development
npm ci
npm run check
npm run build
node scripts/visual-check.mjsAutomated checks do not replace a complete mainnet sync, real account registration, public cast, and independent human test.
License
Original code and documentation are MIT licensed. Snapchain retains its upstream GPL-3.0 license.
