Self-Host Your Own Happy Server
Run your own relay server and keep control over your Claude Code mobile setup.
Why Run Your Own Server?
When you self-host the Happy Server, you get:
- Your hardware - Your encrypted sessions and your account records are stored on your machine
- No limits - Set your own rate limits and storage
- Team control - Run one server for your whole team
The server is about 12,000 lines of TypeScript. You can read it yourself to verify it just forwards encrypted messages.
Quick Start
Clone and Build
# Get the code
git clone https://github.com/slopus/happy
cd happy
# Build with Docker, from the monorepo root
docker build -t happy-server:latest -f Dockerfile .
This image is the standalone server: an embedded Postgres (PGlite) and uploaded files in /data, with no Postgres, Redis, or S3 to run beside it.
Run the Server
# Generate the master secret once and keep the file
echo "HANDY_MASTER_SECRET=$(openssl rand -hex 32)" > happy.env
chmod 600 happy.env
docker run -d \
--name happy-server \
-p 3005:3005 \
-v "$PWD/happy-data:/data" \
--env-file happy.env \
-e PORT=3005 \
--restart unless-stopped \
happy-server:latest
HANDY_MASTER_SECRET: Required. A random secret for auth tokens and server-side encryption. Reuse the samehappy.envwhen you recreate the container, or existing sign-ins stop working.-v "$PWD/happy-data:/data": Keeps the database and uploads in./happy-dataon the host. Without it they live in an anonymous Docker volume.PORT: The port the server listens on (3005).
The standalone image keeps its database in PGlite and ignores DATABASE_URL. To use your own Postgres, see Docker Compose with Postgres.
Configure Your Devices
On your phone:
- Before signing in, tap the gear at the top of the Happy app's first screen. It opens Server.
- Enter
http://your-server:3005as the Server URL and save. The app checks that it is a Happy server.
Already signed in? The setting is then in the developer menu: in Settings, tap Version ten times to turn on developer mode, then open Developer Tools → API Endpoint and restart the app. Sign out and back in after changing the server.
On your computer:
export HAPPY_SERVER_URL="http://your-server:3005"
# Configure your CLI to use your server
Happy Desktop has no server setting yet. Its Mobile Access uses the server named by HAPPY_AGENT_HAPPY_SERVER_URL or HAPPY_SERVER_URL in the environment its agent runs with, otherwise the server saved with its pairing or with the Happy CLI login it imported, otherwise Happy's public server.
Your Happy setup now runs through your own server.
Production Setup with HTTPS
For real use, you want HTTPS. Here's the easiest way with Caddy:
# Install Caddy (auto-manages SSL certificates)
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
# Configure reverse proxy
sudo tee /etc/caddy/Caddyfile <<EOF
your-domain.com {
reverse_proxy localhost:3005
}
EOF
# Start Caddy
sudo systemctl restart caddy
Now use https://your-domain.com as the Server URL on your phone and in HAPPY_SERVER_URL.
Docker Compose Setup
The standalone server needs nothing beside it:
# Generate the master secret once, into .env next to docker-compose.yml
echo "HANDY_MASTER_SECRET=$(openssl rand -hex 32)" > .env
chmod 600 .env
# docker-compose.yml
services:
happy-server:
image: happy-server:latest
ports:
- "3005:3005"
restart: unless-stopped
environment:
- HANDY_MASTER_SECRET=${HANDY_MASTER_SECRET}
- PORT=3005
volumes:
- ./happy-data:/data
Run with: docker compose up -d
Docker Compose with Postgres
To keep data in your own Postgres instead, build the other image, Dockerfile.server, which runs the server against DATABASE_URL:
docker build -t happy-server-pg:latest -f Dockerfile.server .
# Generate both secrets once, into .env
{
echo "HANDY_MASTER_SECRET=$(openssl rand -hex 32)"
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)"
} > .env
chmod 600 .env
# docker-compose.yml
services:
happy-server:
image: happy-server-pg:latest
ports:
- "3005:3005"
restart: unless-stopped
environment:
- NODE_ENV=production
- DATABASE_URL=postgresql://happy:${POSTGRES_PASSWORD}@postgres:5432/happy-server
- HANDY_MASTER_SECRET=${HANDY_MASTER_SECRET}
- PORT=3005
- DATA_DIR=/data
volumes:
- ./happy-data:/data
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:15
restart: unless-stopped
environment:
- POSTGRES_DB=happy-server
- POSTGRES_USER=happy
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U happy -d happy-server"]
interval: 5s
retries: 10
volumes:
postgres_data:
Only the server's port is published; Postgres is reachable only on the Compose network. This image does not migrate on start, so apply the migrations first, and again after each upgrade:
docker compose run --rm happy-server pnpm exec prisma migrate deploy
docker compose up -d
Redis is optional. The server uses it only when REDIS_URL is set, to share live connections across several server processes; one process does not need it. Uploaded files go to /data/files unless you set the S3_* variables.
Where to Host
Option 1: Home Server
Run on any computer at home:
- Raspberry Pi
- Old laptop
- Mac Mini
- Desktop that's always on
Option 2: Cloud VPS
A small VPS from DigitalOcean, Linode, Vultr, Hetzner, or similar.
Option 3: Corporate Network
Run inside your company network for team use. The server works behind firewalls and proxies.
System Requirements
Happy Server is lightweight:
For 1-10 developers:
- 512MB RAM
- 1 CPU core
- 10GB storage
- 100Mbps network
For 10-100 developers:
- 2GB RAM
- 2 CPU cores
- 100GB storage
- 1Gbps network
Monitor Your Server
Check server health:
# View logs
docker logs -f happy-server
# Check health endpoint
curl http://your-server:3005/health
Backup Your Data
The standalone server keeps its database and uploads in ./happy-data. The database is a live Postgres data directory, so stop the server while you copy it:
docker stop happy-server
tar -czf backup-$(date +%Y%m%d).tar.gz ./happy-data
docker start happy-server
With your own Postgres, back it up with pg_dump as usual.
Session messages and metadata in a backup are encrypted with keys on your devices. Account records, such as your public key, an optional profile and GitHub link, and push notification tokens, are not.
Security Notes
The Happy Server design keeps your data safe:
- Server can't read your sessions - Session content is encrypted on your devices before sending
- No account needed - Authentication uses cryptographic proofs
- No logs of your code - Server only logs connection metadata
- Open source - Audit the code yourself
For extra security:
- Use HTTPS in production
- Run behind a VPN for team deployments
- Set up fail2ban for brute force protection
What still leaves your server
Self-hosting moves sync and storage onto your machine. These still talk to other services:
- Model providers. Claude Code, Codex, and the other agents on your computer call their providers' APIs directly: Anthropic, OpenAI, xAI. That traffic never passes through the Happy server.
- Push notifications. The server sends them through Expo's push service, which hands them to Apple or Google. A notification carries its kind, such as "It's ready!", and the session's title as plain text. The Happy CLI can also send one to Expo directly when it cannot attribute it to a session.
- Analytics. The phone app sends product analytics to PostHog whichever server it uses. Turn it off in Settings → Account → Privacy → Analytics. Happy Desktop sends its own, with a Share product analytics switch in its settings. The server itself sends none.
- Optional integrations, only if you configure them: GitHub sign-in, ElevenLabs for voice, and RevenueCat for voice subscriptions.
- Happy Desktop's Tailcat link. Desktop reaches a remote Happy Agent through Tailcat, which may route through Tailscale's free DERP relays. They carry WireGuard ciphertext only. That link does not involve this server.
Advanced: Kubernetes Deployment
For teams using Kubernetes. Build the image from Dockerfile.server, since the standalone image ignores DATABASE_URL, and run pnpm exec prisma migrate deploy with the same secret before each rollout:
apiVersion: apps/v1
kind: Deployment
metadata:
name: happy-server
spec:
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 0
maxSurge: 1
replicas: 1
selector:
matchLabels:
app: happy-server
template:
metadata:
labels:
app: happy-server
spec:
containers:
- name: happy-server
image: happy-server:latest # Use your actual image registry
ports:
- containerPort: 3005
envFrom:
- secretRef:
name: happy-secrets
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: happy-server-pdb
spec:
minAvailable: 1
selector:
matchLabels:
app: happy-server
---
apiVersion: v1
kind: Service
metadata:
name: happy-server
spec:
selector:
app: happy-server
ports:
- port: 3005
targetPort: 3005
type: ClusterIP
Configuration Notes:
- All ports now consistently use 3005 (the application's actual listening port)
- Uses the
happy-secretssecret created in the previous section - Update the image name to match your actual container registry
Kubernetes Secrets
Create a secret file for your environment variables:
# happy-secrets.yaml
apiVersion: v1
kind: Secret
metadata:
name: happy-secrets
type: Opaque
stringData:
DATABASE_URL: "postgresql://happy:A_GENERATED_PASSWORD@postgres-service:5432/happy-server"
HANDY_MASTER_SECRET: "your-secure-master-secret"
PORT: "3005"
NODE_ENV: "production"
Apply the secret:
kubectl apply -f happy-secrets.yaml
Security Note: Replace the values with your actual configuration. For production:
- Use a strong, random HANDY_MASTER_SECRET value, such as
openssl rand -hex 32 - Use a generated database password, such as
openssl rand -hex 24 - Add
REDIS_URLonly if you run more than one replica - Consider using external secret management tools like external-secrets-operator with Vault
Next Steps
After setting up your server: