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 same happy.env when you recreate the container, or existing sign-ins stop working.
  • -v "$PWD/happy-data:/data": Keeps the database and uploads in ./happy-data on 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:

  1. Before signing in, tap the gear at the top of the Happy app's first screen. It opens Server.
  2. Enter http://your-server:3005 as 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:

  1. Server can't read your sessions - Session content is encrypted on your devices before sending
  2. No account needed - Authentication uses cryptographic proofs
  3. No logs of your code - Server only logs connection metadata
  4. 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-secrets secret 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_URL only 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: