Local Development Setup

This guide walks you through setting up the ƒxyz Network monorepo for local development, including the Cloudflare tunnel for HTTPS access and the Agentation MCP integration.

Prerequisites: Node.js 22+, pnpm 10+, Docker (for Neo4j), and cloudflared CLI.

Quick Start

Clone and Install

git clone https://github.com/fxyznetwork/fxallapp.git
cd fxallapp
pnpm install

Configure Environment

cp apps/app/.env.example apps/app/.env.local

Required variables in apps/app/.env.local:

Variable	Description	Where to Get
`NEXT_PUBLIC_PRIVY_APP_ID`	Privy app ID	Privy dashboard
`PRIVY_APP_ID`	Same as above (server-side)	Privy dashboard
`PRIVY_APP_SECRET`	Privy secret key	Privy dashboard
`NEXT_PUBLIC_APP_URL`	`https://dev.fxyz.network`	Fixed value
`NEXT_PUBLIC_API_URL`	`https://dev-api.fxyz.network/api/graphql`	Fixed value
`NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`	WalletConnect project ID	WalletConnect dashboard

Start Neo4j Database

docker compose -f docker/neo4j/docker-compose.yml up -d

Verify: curl http://localhost:7474

Start Dev Servers + Tunnel

# Terminal 1: Start all apps
pnpm dev

# Terminal 2: Start Cloudflare tunnel (HTTPS access)
cloudflared tunnel run fxyz-dev

Architecture

Port Mapping

App	Port	Local URL	Tunnel URL
app (dashboard)	3000	`http://localhost:3000`	`https://dev.fxyz.network`
web (marketing)	3001	`http://localhost:3001`	-
api (GraphQL)	3002	`http://localhost:3002`	`https://dev-api.fxyz.network`
docs	3004	`http://localhost:3004`	-
agentation (MCP)	4747	`http://localhost:4747`	`https://dev-agentation.fxyz.network`

Use the tunnel URL for the main app (https://dev.fxyz.network), not localhost:3000. Privy authentication requires HTTPS on a trusted domain.

Cloudflare Tunnel

The tunnel maps HTTPS domains to local ports, solving the Privy HTTPS requirement:

Browser (HTTPS) → Cloudflare Edge → cloudflared tunnel → localhost

Tunnel config: ~/.cloudflared/config.yml

tunnel: fxyz-dev
credentials-file: ~/.cloudflared/[tunnel-id].json
ingress:
  - hostname: dev.fxyz.network
    service: http://localhost:3000
  - hostname: dev-api.fxyz.network
    service: http://localhost:3002
  - hostname: dev-agentation.fxyz.network
    service: http://localhost:4747
  - service: http_status:404

DNS CNAMEs for dev.fxyz.network, dev-api.fxyz.network, and dev-agentation.fxyz.network point to [tunnel-id].cfargotunnel.com in Cloudflare (proxied).

Agentation MCP

Agentation provides a visual feedback overlay in the app that communicates with Claude Code via MCP.

How It Works

Browser                          Server                    Claude Code
┌─────────────────┐    HTTPS    ┌──────────────────┐  MCP  ┌──────────┐
│ <Agentation />  │ ─────────→ │ agentation-mcp   │ ────→ │ Claude   │
│ React overlay   │  endpoint  │ HTTP :4747       │ stdio │ Code CLI │
│ User annotates  │            │ Stores data      │       │ Reads    │
└─────────────────┘            └──────────────────┘       └──────────┘

React component renders in dev mode (providers.tsx)
User creates annotations (click elements, describe changes)
Annotations POST to https://dev-agentation.fxyz.network (tunneled to :4747)
agentation-mcp MCP server exposes annotations to Claude Code via stdio

Configuration

React side (apps/app/app/providers.tsx):

{process.env.NODE_ENV === "development" && (
  <Agentation endpoint="https://dev-agentation.fxyz.network" />
)}

MCP side (mcp.json / .mcp.json):

{
  "agentation": {
    "type": "stdio",
    "command": "npx",
    "args": ["agentation-mcp", "server"]
  }
}

Patch: Dev Domain Detection

Agentation checks window.location.hostname to enable React component detection (only on localhost by default). We patch it via pnpm patch to also accept *.fxyz.network domains.

The patch is in patches/agentation.patch and applied automatically on pnpm install.

Monorepo Structure

fxallapp/
├── apps/
│   ├── app/          # Main dashboard (Next.js 16, port 3000)
│   ├── api/          # GraphQL API (Next.js 16, port 3002)
│   ├── web/          # Marketing website (port 3001)
│   ├── docs/         # Documentation - Fumadocs (port 3004)
│   └── email/        # Email templates (React Email)
├── packages/
│   ├── auth/         # Privy v3 authentication
│   ├── design-system/ # shadcn/ui components
│   ├── graphql/      # Apollo Client + schema
│   ├── neo4j/        # Neo4j client, services, migrations
│   ├── contexts/     # React context providers
│   ├── visualization/ # 3D/graph visualization
│   ├── solana/       # Solana blockchain integration
│   ├── types/        # Shared TypeScript types
│   └── trading/      # Market-routing and engine package
├── patches/          # pnpm patches (e.g., agentation)
└── docker/           # Docker Compose files

Environment Variables

Required

Variable	Description
`NEO4J_URI`	Neo4j connection (`bolt://localhost:7687`)
`NEO4J_USER`	Neo4j username
`NEO4J_PASSWORD`	Neo4j password
`PRIVY_APP_ID`	Privy application ID
`PRIVY_APP_SECRET`	Privy secret key
`NEXT_PUBLIC_PRIVY_APP_ID`	Client-side Privy app ID
`NEXT_PUBLIC_APP_URL`	`https://dev.fxyz.network`
`NEXT_PUBLIC_API_URL`	`https://dev-api.fxyz.network/api/graphql`

Optional

Variable	Description	Default
`CLUSTER_ENV`	Solana cluster	`devnet`
`HELIUS_API_KEY`	Helius RPC key	-
`BRIDGE_API_KEY`	Bridge.xyz fiat rails	-
`RWA_API_KEY`	RWA.xyz API	-
`STALWART_API_URL`	Email server URL	Gracefully skipped
`STALWART_API_TOKEN`	Email server token	Gracefully skipped

Missing optional vars (Stalwart, Bridge, RWA) will log warnings but won't crash the app.

Development Commands

# Start all apps (via Turbo)
pnpm dev

# Build all packages
pnpm build

# Run specific app
pnpm --filter @repo/app dev
pnpm --filter @repo/api dev

# Type check
pnpm typecheck

# Lint
pnpm lint

Troubleshooting

Port Conflicts

# Find what's using a port
ss -tlnp | grep :3000

# Kill stale Next.js servers
kill $(lsof -ti:3000,3002)

Privy Not Working

Ensure you're accessing via https://dev.fxyz.network (not localhost)
Verify NEXT_PUBLIC_PRIVY_APP_ID matches your Privy dashboard
Check that dev.fxyz.network is whitelisted in Privy's allowed origins

Tunnel Not Connecting

# Check tunnel status
cloudflared tunnel info fxyz-dev

# Restart tunnel
cloudflared tunnel run fxyz-dev

# Verify DNS
dig dev.fxyz.network

API Returns 500

Check Neo4j is running: curl http://localhost:7474
Check API logs in the pnpm dev terminal output
Missing env vars show as warnings in the API startup logs

Local Development Setup

On this page