When I started using Happier seriously, I wanted control over where session data lives and how the relay is configured. The cloud relay works fine, but self-hosting gives you complete ownership.

This is the workflow I use to run a private Happier relay.

TL;DR

Docker (recommended starting point):

docker pull happierdev/relay-server:stable
docker run -d \
  -p 3600:3600 \
  -e HANDY_MASTER_SECRET="$(openssl rand -hex 32)" \
  -e NODE_ENV=production \
  --name happier-relay \
  happierdev/relay-server:stable

Or managed install:

happier relay host install --mode system

Then configure clients to use your relay URL instead of the default.

The problem

Using the cloud relay means:

• Session data passes through infrastructure you don't control
• No control over data residency or retention policies
• Dependent on the cloud service's availability
• Limited customization of rate limits and policies

For some workflows, that's fine. For others, you want:

• Complete ownership of infrastructure
• Data stays on your network or chosen hosting
• Custom authentication and access policies
• Control over updates and configuration

What I tried first (and where I bounced off)

• Cloud relay: Works well, but I wanted data on my infrastructure.
• Building from source: Possible but requires keeping up with dependencies and build steps.
• Custom relay implementation: Would be a maintenance burden.

Self-hosting the official relay solved this:

• Pre-built Docker images
• Managed install option
• Same relay protocol as the cloud version
• Full control over deployment

If you're new to Happier

Happier is an open-source companion app for AI coding agents like Claude Code, Codex, and OpenCode.

The relay is the server component that:

• Routes messages between your devices
• Stores session metadata
• Handles authentication
• Provides end-to-end encrypted message passing

When you self-host the relay, your sessions and approvals never leave your infrastructure.

Get set up:

• GitHub: https://github.com/happier-dev/happier
• Self-hosting docs: https://docs.happier.dev/self-hosting
• Discord: https://discord.gg/W6Pb8KuHfg

Prerequisites

Choose one deployment method:

For Docker (recommended)

• Docker installed
• A host with a public IP or private network access
• Port 3600 available (or configure a different port)

For managed install

• A Linux or macOS machine
• Happier CLI installed
• Ability to run services (systemd or user services)

For runner (advanced)

• Node.js or Bun
• Process manager (PM2, systemd, etc.)
• Manual artifact management

Option 1: Docker (recommended for most people)

Docker is the fastest way to self-host with minimal configuration.

1) Pull the image

docker pull happierdev/relay-server:stable

Available tags:

• stable: Production releases
• preview: Preview releases
• dev: Development builds

For production use: stick with stable.

2) Generate a master secret

The master secret encrypts data at rest and derives authentication tokens.

openssl rand -hex 32

Save this value securely. Do not lose it: rotating the secret makes existing data unreadable.

3) Run the container

docker run -d \
  -p 3600:3600 \
  -e HANDY_MASTER_SECRET="your-secret-from-step-2" \
  -e NODE_ENV=production \
  --name happier-relay \
  --restart unless-stopped \
  happierdev/relay-server:stable

4) Verify it's running

docker logs happier-relay

You should see:

[info] Happier relay server starting...
[info] Listening on http://0.0.0.0:3600

5) Configure clients to use your relay

From the Happier app:

1. Go to Settings → Server
2. Add a new server profile
3. Enter your relay URL: http://your-server-ip:3600
4. Save and connect

From the Happier CLI:

happier config set relay.url http://your-server-ip:3600

See Self-hosting quickstart for detailed client setup.

Option 2: Managed install (for service-based deployment)

The managed install creates a system service that starts on boot and provides update commands.

1) Install the Happier CLI

Follow the CLI installation guide.

2) Install the relay as a system service

happier relay host install --mode system

For user-mode installation (no sudo required):

happier relay host install --mode user

3) Configure the master secret

Edit the service configuration:

sudo nano /etc/happier-relay/env

Add:

HANDY_MASTER_SECRET=your-secret-here
NODE_ENV=production

4) Start the relay

happier relay host start

5) Check status

happier relay host status

You should see:

Relay service: active (running)

6) Configure clients

Same as Docker option: add your relay URL to client settings.

Option 3: Runner (for advanced users)

The runner fetches and verifies relay artifacts on startup, then runs the server binary.

This is for setups where:

• You already have a process manager
• You want artifact downloads on restart
• You don't want Docker or service management

1) Run the relay server package

npx --yes --package @happier-dev/relay-server happier-server \
  --master-secret "your-secret-here" \
  --port 3600

2) Use with a process manager

Example with PM2:

pm2 start npx --name happier-relay -- \
  --yes --package @happier-dev/relay-server happier-server \
  --master-secret "your-secret-here" \
  --port 3600
pm2 save

See Self-host runtime documentation for runner details.

Environment configuration

Key environment variables:

See Environment variables documentation for the complete list.

Authentication setup

By default, the relay uses password-based authentication.

For production, consider:

• GitHub OAuth: See GitHub auth
• OIDC: See OIDC auth
• mTLS: See mTLS auth

HTTPS and reverse proxy

For production use, put the relay behind a reverse proxy with HTTPS.

Example with nginx:

server {
    listen 443 ssl;
    server_name relay.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3600;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Then clients connect to: https://relay.example.com

Updates

Docker

docker pull happierdev/relay-server:stable
docker stop happier-relay
docker rm happier-relay
# Re-run the docker run command with the new image

Managed install

happier relay host install --mode system
happier relay host restart

Runner

The runner fetches new artifacts on restart automatically.

Troubleshooting

Symptom: Container exits immediately

Likely cause:

• Missing or invalid HANDY_MASTER_SECRET
• Port already in use

Fix:

1. Check container logs: docker logs happier-relay
2. Verify environment variables are set
3. Check port availability: lsof -i :3600

Symptom: Clients can't connect

Likely cause:

• Firewall blocking port 3600
• Relay not listening on correct interface
• Client has wrong relay URL

Fix:

1. Verify relay is running: docker ps or happier relay host status
2. Check firewall: sudo ufw allow 3600/tcp
3. Test connectivity: curl http://your-server-ip:3600
4. Verify client relay URL matches server address

Symptom: "Authentication failed" errors

Likely cause:

• Master secret changed between relay and client registration
• Relay restarted without preserving authentication tokens

Fix:

1. Verify HANDY_MASTER_SECRET is consistent
2. Re-register clients if master secret changed
3. Check relay logs for auth errors

Symptom: Updates not applying

Docker:

• Ensure you're pulling the image before recreating container
• Check image tag hasn't changed

Managed install:

• Run happier relay host install again
• Restart the service after install

Common questions

Do I need to self-host?

No. The cloud relay works fine for most users.

Self-host when you:

• Need data residency guarantees
• Want complete infrastructure control
• Have compliance requirements
• Prefer self-managed services

Can I migrate from cloud to self-hosted?

Yes, but sessions don't automatically migrate.

Workflow:

1. Set up self-hosted relay
2. Configure clients to use new relay URL
3. Existing cloud sessions remain on cloud relay
4. New sessions use self-hosted relay

Is end-to-end encryption still active?

Yes. E2E encryption is client-side, independent of which relay you use.

The relay operator (you or the cloud provider) cannot read session contents regardless.

How do I backup the relay data?

The relay stores data in its data directory.

Docker: Add a volume mount:

-v /path/to/data:/data

Managed install: Data location varies by OS, check: happier relay host status

Backup:

1. Stop the relay
2. Copy the data directory
3. Restart the relay

Can I run multiple relay instances?

Yes, for high availability or load balancing.

Requirements:

• Shared data store (database)
• Load balancer in front
• Same HANDY_MASTER_SECRET across all instances

See Environment documentation for clustering configuration.

Related guides

• How to run Happier from your phone
• Happier vs Claude Code Remote Control