Fork Guide Getting Started

Fork Guide: Getting Started

This guide walks you through forking ZAO OS and deploying your own community instance. By the end, you'll have a working app with your branding, your channels, and your members.

---

Prerequisites

You'll need:

• Node.js 18+ and npm
• A Supabase project (free tier works)
• A Neynar account (for Farcaster integration)
• A Farcaster account to use as your app's identity
• A Vercel account (or any Node.js hosting)

Optional but recommended:

• Upstash Redis account (for rate limiting)
• Alchemy API key (for ENS resolution and webhooks)
• PostHog account (for analytics)

---

Step 1: Fork & Clone

# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/ZAOOS.git
cd ZAOOS
npm install

npm install also runs postinstall which patches packages and copies XMTP WASM files.

---

Step 2: Configure Your Community

Open community.config.ts — this is the single source of truth for everything community-specific.

export const communityConfig = {
  // Your community name and tagline
  name: 'YOUR COMMUNITY',
  tagline: 'Your tagline here',

  // Your color scheme
  colors: {
    primary: '#f5a623',        // Accent color (buttons, highlights)
    primaryHover: '#ffd700',   // Hover state
    background: '#0a1628',     // Main background (dark theme)
    surface: '#0d1b2a',        // Card/panel backgrounds
    surfaceLight: '#1a2a3a',   // Lighter surfaces
  },

  // Your Farcaster setup
  farcaster: {
    appFid: YOUR_APP_FID,                // Your app's Farcaster ID
    channels: ['your-channel'],          // Farcaster channels to monitor
    defaultChannel: 'your-channel',      // Default channel for chat
  },

  // Who can access the admin dashboard
  adminFids: [YOUR_FID],
  adminWallets: [],

  // ... rest of config
};

See Fork Guide: Customization for a complete walkthrough of every config option.

---

Step 3: Set Up Environment Variables

Copy the example env file:

cp .env.example .env.local

Required Variables

Variable	Where to Get It
NEXT_PUBLIC_SUPABASE_URL	Supabase project settings → API
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase project settings → API
SUPABASE_SERVICE_ROLE_KEY	Supabase project settings → API (keep secret!)
NEYNAR_API_KEY	neynar.com dashboard
SESSION_SECRET	Generate: openssl rand -hex 32
APP_SIGNER_PRIVATE_KEY	Generate with the script below
NEXT_PUBLIC_APP_URL	Your deployment URL

Generate App Wallet

npx tsx scripts/generate-wallet.ts

This generates a fresh wallet for your app to sign Farcaster actions. Never use a personal wallet. Copy the private key to APP_SIGNER_PRIVATE_KEY.

Optional Variables

Variable	Purpose
UPSTASH_REDIS_REST_URL	Rate limiting
UPSTASH_REDIS_REST_TOKEN	Rate limiting
ALCHEMY_API_KEY	ENS resolution, webhooks
POSTHOG_KEY	Analytics
PERSPECTIVE_API_KEY	AI content moderation
TWITTER_CLIENT_ID / SECRET	X cross-posting
BLUESKY_IDENTIFIER / PASSWORD	Bluesky cross-posting
DISCORD_BOT_TOKEN	Discord publishing
TELEGRAM_BOT_TOKEN	Telegram broadcasting
LIVEPEER_API_KEY	Streaming
HMS_ACCESS_KEY / SECRET	100ms voice rooms
ARWEAVE_WALLET_JSON	Arweave music uploads

---

Step 4: Set Up the Database

Run the Supabase setup scripts to create tables and enable RLS:

# The SQL files are in scripts/
# Run them in your Supabase SQL editor or via CLI

Check scripts/ for the database setup SQL files. They create all necessary tables with Row-Level Security policies.

---

Step 5: Register Your Farcaster Signer

Your app needs a registered signer to post casts and react on behalf of users. This connects your generated app wallet to your Farcaster app FID via Neynar.

The signer registration flow is handled through the app's auth endpoints — start the dev server and go through the sign-in flow to register.

---

Step 6: Run Locally

npm run dev

This starts Next.js with Turbopack. Visit http://localhost:3000.

Verify It Works

1. You should see the landing page with your community name
2. Sign in with Farcaster
3. Check that chat loads messages from your configured channel
4. Test the music player by sharing a Spotify/YouTube/Audius link

---

Step 7: Deploy

Vercel (Recommended)

1. Push your fork to GitHub
2. Import the repo in Vercel
3. Add all environment variables
4. Deploy

Other Platforms

ZAO OS is a standard Next.js app. It works on any platform that supports Next.js:

• Railway
• Render
• AWS Amplify
• Self-hosted with npm run build && npm start

---

What's Next

• Fork Guide: Customization — branding, theming, navigation
• Fork Guide: Features — enable/disable features, add integrations
• Fork Guide: Gating & Access — control who can access your app
• Fork Guide: Database & Auth — deep dive on Supabase and auth