Local Setup

Environment Setup

Complete guide to setting up your development environment for HIVE Protocol. This covers all prerequisites, tools, and configurations needed to run the application locally.

Overview

┌─────────────────────────────────────────────────────────────────┐
│                   Development Environment                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Required Software:                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  Node.js    │  │    Git      │  │   Editor    │              │
│  │   v18+      │  │   v2.30+    │  │  (VS Code)  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                                                                  │
│  Cloud Services:                                                 │
│  ┌─────────────┐  ┌─────────────────────────────┐               │
│  │  Supabase   │  │  AI Provider (1+ required)  │               │
│  │  (Database) │  │  OpenAI / Anthropic / Google│               │
│  └─────────────┘  └─────────────────────────────┘               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

System Requirements

Minimum Requirements

Component	Minimum	Recommended
Node.js	18.x	20.x LTS
npm	9.x	10.x
RAM	4 GB	8 GB
Disk Space	1 GB	2 GB
OS	macOS 12+, Ubuntu 20.04+, Windows 10+	Latest stable

Browser Support

Browser	Minimum Version
Chrome	90+
Firefox	90+
Safari	14+
Edge	90+

Installing Node.js

Node.js is required to run the development server and build the application.

Using nvm (Recommended)

Node Version Manager allows you to install and switch between Node.js versions.

macOS/Linux:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Restart terminal or source profile
source ~/.bashrc  # or ~/.zshrc

# Install Node.js 20 LTS
nvm install 20
nvm use 20
nvm alias default 20

# Verify installation
node --version   # Should show v20.x.x
npm --version    # Should show 10.x.x

Windows:

# Install nvm-windows from:
# https://github.com/coreybutler/nvm-windows/releases

# Then in PowerShell (as Administrator):
nvm install 20
nvm use 20

# Verify installation
node --version
npm --version

Direct Installation

If you prefer not to use nvm:

# macOS with Homebrew
brew install node@20

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows
# Download installer from https://nodejs.org/

Installing Git

Git is required to clone the repository and manage version control.

# macOS
brew install git

# Ubuntu/Debian
sudo apt update
sudo apt install git

# Windows
# Download from https://git-scm.com/download/win

# Verify installation
git --version   # Should show 2.30+

# Configure Git (first time setup)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Code Editor Setup

VS Code (Recommended)

Download from code.visualstudio.com

Recommended Extensions:

# Install via command line
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension bradlc.vscode-tailwindcss
code --install-extension Prisma.prisma
code --install-extension ms-vscode.vscode-typescript-next

Workspace Settings (.vscode/settings.json):

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

Cloud Service Accounts

Supabase Account

Go to supabase.com
Click "Start your project" and sign up
Create a new organization (or use existing)
Create a new project:
Choose a name (e.g., "hive-protocol-dev")
Generate a strong database password (save it!)
Select a region closest to you
Wait for project to be provisioned (2-3 minutes)

Get Your Credentials:

Project Settings > API

Copy these values:
- Project URL: https://xxxxx.supabase.co
- anon public key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
- service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... (keep secret!)

AI Provider Accounts

You need at least one AI provider. We recommend starting with OpenAI.

OpenAI:

Go to platform.openai.com
Sign up / Sign in
Navigate to API Keys
Create a new secret key
Copy and save securely

Anthropic:

Go to console.anthropic.com
Sign up / Sign in
Navigate to API Keys
Create a new key
Copy and save securely

Google AI:

Go to aistudio.google.com
Sign in with Google account
Get API Key
Copy and save securely

Project Setup

Clone the Repository

# Clone the repo
git clone https://github.com/your-org/hive-protocol.git
cd hive-protocol

# Check the structure
ls -la

Install Dependencies

# Install all packages
npm install

# This installs ~200+ packages including:
# - Next.js (framework)
# - React (UI library)
# - Supabase client (database)
# - Tailwind CSS (styling)
# - shadcn/ui (components)
# - Zod (validation)
# - And many more...

Configure Environment Variables

# Create your local environment file
cp .env.example .env

# Edit with your values
nano .env  # or use your preferred editor

Required .env Variables:

# Supabase Configuration (Required)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# AI Providers (At least one required)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=AIza...

Optional .env Variables:

# For local Supabase development
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Analytics (optional)
NEXT_PUBLIC_ANALYTICS_ID=UA-...

# Feature flags (optional)
NEXT_PUBLIC_ENABLE_DEMO_MODE=false

Verify Installation

Run Development Server

# Start the development server
npm run dev

# You should see:
# > next dev
# > Local: http://localhost:3000
# > Ready in X.Xs

Access the Application

Open http://localhost:3000 in your browser
You should see the HIVE Protocol landing page
Click "Get Started" or "Login"
Create a new account to verify auth is working

Run Type Check

# Verify TypeScript compilation
npm run typecheck

# Should complete with no errors

Run Linter

# Check for code issues
npm run lint

# Should complete with no errors (or only warnings)

Run Build

# Test production build
npm run build

# Should complete successfully

Directory Structure

hive-protocol/
├── app/                    # Next.js App Router pages
│   ├── (auth)/             # Auth-related pages
│   ├── admin/              # Admin dashboard
│   ├── agents/             # Agent management
│   ├── dashboard/          # Main dashboard
│   ├── docs/               # Documentation pages
│   ├── settings/           # User settings
│   ├── swarms/             # Swarm management
│   ├── tools/              # Tool management
│   ├── globals.css         # Global styles
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Landing page
├── components/             # React components
│   ├── admin/              # Admin components
│   ├── auth/               # Auth components
│   ├── dashboard/          # Dashboard components
│   ├── marketing/          # Marketing pages
│   ├── settings/           # Settings components
│   ├── swarm/              # Swarm components
│   ├── tools/              # Tool components
│   └── ui/                 # Base UI (shadcn)
├── hooks/                  # Custom React hooks
│   ├── use-agents.ts
│   ├── use-auth.ts
│   ├── use-swarm.ts
│   └── ...
├── lib/                    # Utility functions
│   ├── supabase.ts         # Supabase client
│   ├── utils.ts            # General utilities
│   └── ...
├── store/                  # Zustand state store
├── supabase/               # Supabase configuration
│   ├── functions/          # Edge functions
│   └── migrations/         # Database migrations
├── .env                    # Environment variables
├── .env.example            # Example env file
├── next.config.js          # Next.js configuration
├── package.json            # Dependencies
├── tailwind.config.ts      # Tailwind configuration
└── tsconfig.json           # TypeScript configuration

Next Steps

[Supabase Setup](/docs/local-setup/supabase-setup): Configure your database
[Edge Functions](/docs/local-setup/edge-functions): Deploy serverless functions
[Troubleshooting](/docs/local-setup/troubleshooting): Common issues and solutions

API Reference

Webhooks API

Supabase Setup

Environment Setup

Environment Setup

Overview

System Requirements

Minimum Requirements

Browser Support

Installing Node.js

Using nvm (Recommended)

Direct Installation

Installing Git

Code Editor Setup

VS Code (Recommended)

Cloud Service Accounts

Supabase Account

AI Provider Accounts

Project Setup

Clone the Repository

Install Dependencies

Configure Environment Variables

Verify Installation

Run Development Server

Access the Application

Run Type Check

Run Linter

Run Build

Directory Structure

Next Steps

Cookie Preferences