Getting Started & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Happy project is a comprehensive TypeScript and Swift monorepo designed to enable remote control and session sharing for Claude Code. It features end-to-end encryption (E2E) using AES-256-GCM and TweetNaCl, ensuring that the central server acts only as a zero-knowledge relay. The architecture encompasses multiple clients—including a Node.js CLI, a React Native mobile/web app, and native macOS and Android applications—supported by both Fastify (Docker) and Cloudflare Workers backends.
Getting started with the Happy ecosystem requires setting up a monorepo environment that utilizes Yarn 4 and Corepack. Each application within the monorepo has specific environmental requirements, ranging from PostgreSQL and Redis for the Docker-based server to Cloudflare D1 and R2 for the edge-native workers. This guide outlines the core setup procedures, environmental configurations, and essential commands to initialize the development environment.
Sources: CLAUDE.md:1-25, knowledge.md:1-20, apps/server/workers/README.md:1-15
Core Monorepo Setup
The Happy ecosystem is managed as a monorepo using Yarn workspaces. This structure allows for sharing dependencies and internal packages like @magic-agent/protocol (shared Zod schemas) and @magic-agent/errors (unified error handling) across all applications.
Prerequisites & Installation
Before working on any sub-project, the root environment must be initialized. The project requires Node.js version 18 or higher.
# Enable Corepack to use Yarn 4
corepack enable
# Install all dependencies and build shared packages
yarn install
# Build specific shared packages if needed
yarn build:protocol
yarn build:errors
Sources: knowledge.md:7-17, CLAUDE.md:112-120
Workspace Dependencies
The project relies on internal shared packages located in the packages/ directory. These are linked via the workspace:* protocol in package.json files.
| Package | Purpose |
|---|---|
@magic-agent/protocol | Shared Zod schemas for API types (Source of Truth) |
@magic-agent/errors | Standardized AppError class and error codes |
@happy/lint-rules | Custom oxlint/ESLint rules for the codebase |
Sources: CLAUDE.md:122-155, knowledge.md:23-28
Component Architecture and Setup
The setup process varies significantly depending on which part of the system is being developed. The following diagram illustrates the connectivity required for a full local development stack.
This diagram shows the relationship between client applications and the two backend implementation choices (Docker-based or Cloudflare-based).
Sources: CLAUDE.md:195-210, apps/server/workers/README.md:116-135
1. Server Setup (Docker/Fastify)
The Docker-based server uses Fastify and Prisma ORM. It requires several infrastructure components to be running locally or via Docker.
- Requirements: Node.js 20, FFmpeg, Python3, PostgreSQL, Redis.
- Database: Managed via Prisma. Do not run migrations manually; use the provided yarn commands.
| Command | Action |
|---|---|
yarn db | Start local PostgreSQL in Docker |
yarn generate | Generate Prisma client types |
yarn migrate | Run pending Prisma migrations |
yarn dev | Start server in development mode |
Sources: apps/server/docker/CLAUDE.md:15-45
2. Server Setup (Cloudflare Workers)
The Workers implementation is an edge-native backend using Hono and Cloudflare's D1 (SQL) and R2 (Storage).
# Initial configuration
cp .dev.vars.example .dev.vars
# Setup local D1 database
yarn db:migrate
# Start local Wrangler server
yarn dev
The verification script verify-cloudflare-setup.sh is used to ensure the Cloudflare environment is correctly configured with the necessary Account IDs and bucket bindings.
Sources: apps/server/workers/README.md:21-35, apps/server/workers/scripts/verify-cloudflare-setup.sh:100-150
3. Native Client Setup
- macOS: Requires Xcode 15+ and Swift 5.9. Development targets macOS 14.0+. Use
open Happy.xcodeprojto begin. - Android: Requires Android Studio Hedgehog+ and Kotlin 1.9.22. Uses Hilt for DI and Jetpack Compose for the UI.
- React Native (Expo): Requires the Expo Go app or simulators. Managed via
yarn start.
Sources: apps/macos/README.md:10-35, apps/mobile/android/CLAUDE.md:50-70, apps/web/react/CLAUDE.md:10-25
Environment Variables & Security
Happy uses a strict environment variable convention across all projects. Sensitive data is never committed to Git.
Standard Environment Files
.env.example: Template for all required variables..env.dev: Local development defaults..env: Active environment (ignored by Git)..dev.vars: Used specifically for Cloudflare Workers local secrets.
Sources: CLAUDE.md:270-285
Secret Generation
The system requires cryptographic keys for E2E encryption and JWT signing. A utility script is provided in the server directory to generate these:
cd apps/server/docker
./scripts/generate-secrets.sh
This generates the HAPPY_MASTER_SECRET (32-byte hex) and TweetNaCl keypairs for client communication.
Sources: CLAUDE.md:300-315, apps/server/docker/CLAUDE.md:55-65
Authentication Flow Setup
Setting up a connection between a CLI and a mobile client follows a specific cryptographic challenge-response sequence.
This sequence represents the standard "Pairing" flow used to initialize a secure session between a new terminal and a mobile device.
Sources: CLAUDE.md:215-225, apps/server/workers/README.md:54-65
Summary
Setting up the Happy ecosystem involves initializing the monorepo with Yarn 4, configuring project-specific environment variables, and ensuring backend services (either Docker-based or Cloudflare-based) are properly provisioned. The security of the system relies on the HAPPY_MASTER_SECRET and client-side keypairs generated during the setup phase. Once the backend is active, clients can be paired using the QR-code-based challenge-response authentication mechanism.
Sources: CLAUDE.md:430-445, knowledge.md:35-45