- CLI
- 0.2.17
- プレビュー ref
- a2c45c8
セッションデータの保存場所やリレーの設定を自分で管理したいなら、自分のリレーを運用できます。クラウドリレーで問題なく使えますが、セルフホストならすべてを自分で所有できます。
このガイドでは、プライベートな Happier リレーの運用方法を説明します。
要点
Docker（まずはこちらがおすすめ）：
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または管理型インストール：
happier relay host install --mode systemそのあと、クライアントがデフォルトではなく自分のリレー URL を使うように設定します。
課題
クラウドリレーを使うということは：
- セッションデータが自分で管理していないインフラを通る
- データの保存場所や保持ポリシーを管理できない
- クラウドサービスの可用性に依存する
- レート制限やポリシーのカスタマイズが限られる
ワークフローによってはそれで問題ありません。そうでない場合に必要なのは：
- インフラを完全に自分で所有すること
- データが自分のネットワークや選んだホスティング内にとどまること
- 独自の認証とアクセスポリシー
- アップデートと設定の管理
よくある方法とそのトレードオフ
- クラウドリレー：問題なく動きますが、データは自分のインフラにはありません。
- ソースからビルド：可能ですが、依存関係とビルド手順を追い続ける必要があります。
- 独自のリレー実装：保守の負担になります。
公式リレーのセルフホスト なら、これを解決できます：
- ビルド済みの Docker イメージ
- 管理型インストールの選択肢
- クラウド版と同じリレープロトコル
- デプロイを完全に管理できる
Happier を初めて使う場合
Happier は、Claude Code、Codex、OpenCode などの AI コーディングエージェント向けのオープンソースのコンパニオンアプリです。
リレーはサーバー側のコンポーネントで、次の役割を持ちます：
- デバイス間のメッセージを中継する
- セッションのメタデータを保存する
- 認証を処理する
- エンドツーエンド暗号化されたメッセージの受け渡しを提供する
リレーをセルフホストすれば、セッションと承認が自分のインフラの外に出ることはありません。
セットアップ：
- GitHub: https://github.com/happier-dev/happier
- セルフホストのドキュメント: https://docs.happier.dev/self-hosting
- Discord: https://discord.gg/W6Pb8KuHfg
前提条件
デプロイ方法をひとつ選びます。
Docker の場合（おすすめ）
- Docker がインストールされている
- パブリック IP またはプライベートネットワークでアクセスできるホスト
- ポート 3600 が空いている（または別のポートを設定する）
管理型インストールの場合
- Linux または macOS のマシン
- Happier CLI がインストールされている
- サービスを実行できる（systemd またはユーザーサービス）
ランナーの場合（上級者向け）
- Node.js または Bun
- プロセスマネージャー（PM2、systemd など）
- アーティファクトの手動管理
方法 1：Docker（ほとんどの人におすすめ）
Docker なら、少ない設定ですぐにセルフホストを始められます。
1) イメージを取得する
docker pull happierdev/relay-server:stable利用できるタグ：
stable：本番向けリリースpreview：プレビューリリースdev：開発ビルド
本番では stable を使いましょう。
2) マスターシークレットを生成する
マスターシークレットは保存データの暗号化と認証トークンの導出に使われます。
openssl rand -hex 32この値は安全に保管してください。なくさないこと：シークレットを変更すると既存のデータが読めなくなります。
3) コンテナを起動する
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:stable4) 動いているか確認する
docker logs happier-relay次のように表示されるはずです：
[info] Happier relay server starting...
[info] Listening on http://0.0.0.0:36005) クライアントが自分のリレーを使うように設定する
Happier アプリから：
- 設定（Settings）→ サーバー（Server）に進む
- 新しいサーバープロファイルを追加する
- リレー URL を入力する：
http://your-server-ip:3600 - 保存して接続する
Happier CLI から：
happier config set relay.url http://your-server-ip:3600クライアントの詳しい設定は セルフホストのクイックスタート を参照してください。
方法 2：管理型インストール（サービスとしてデプロイする場合）
管理型インストールは、起動時に立ち上がりアップデート用のコマンドも備えたシステムサービスを作成します。
1) Happier CLI をインストールする
CLI のインストールガイド に従ってください。
2) リレーをシステムサービスとしてインストールする
happier relay host install --mode systemユーザーモードでインストールする場合（sudo 不要）：
happier relay host install --mode user3) マスターシークレットを設定する
サービスの設定を編集します：
sudo nano /etc/happier-relay/env次を追加します：
HANDY_MASTER_SECRET=your-secret-here
NODE_ENV=production4) リレーを起動する
happier relay host start5) 状態を確認する
happier relay host status次のように表示されるはずです：
Relay service: active (running)6) クライアントを設定する
Docker の場合と同じく、クライアントの設定にリレー URL を追加します。
方法 3：ランナー（上級者向け）
ランナーは起動時にリレーのアーティファクトを取得・検証してから、サーバーのバイナリを実行します。
次のような環境向けです：
- すでにプロセスマネージャーがある
- 再起動時にアーティファクトをダウンロードしたい
- Docker やサービス管理を使いたくない
1) リレーサーバーのパッケージを実行する
npx --yes --package @happier-dev/relay-server happier-server \
--master-secret "your-secret-here" \
--port 36002) プロセスマネージャーと組み合わせる
PM2 の例：
pm2 start npx --name happier-relay -- \
--yes --package @happier-dev/relay-server happier-server \
--master-secret "your-secret-here" \
--port 3600
pm2 saveランナーの詳細は セルフホストのランタイムのドキュメント を参照してください。
環境変数の設定
主な環境変数：
| 変数 | 用途 | 必須 |
|---|---|---|
HANDY_MASTER_SECRET | 暗号化と認証の導出 | はい |
NODE_ENV | production に設定 | はい |
HAPPIER_RELAY_PORT | 待ち受けるポート | いいえ（デフォルト：3600） |
HAPPIER_RELAY_HOST | バインドするアドレス | いいえ（デフォルト：0.0.0.0） |
一覧は 環境変数のドキュメント を参照してください。
認証の設定
デフォルトでは、リレーはパスワードによる認証を使います。
本番では次も検討してください：
HTTPS とリバースプロキシ
本番では、リレーを HTTPS 対応のリバースプロキシの後ろに置きましょう。
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;
}
}クライアントの接続先は https://relay.example.com になります。
アップデート
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管理型インストール
happier relay host install --mode system
happier relay host restartランナー
ランナーは再起動時に新しいアーティファクトを自動で取得します。
トラブルシューティング
症状：コンテナがすぐに終了する
考えられる原因：
HANDY_MASTER_SECRETがない、または無効- ポートがすでに使われている
対処：
- コンテナのログを確認する：
docker logs happier-relay - 環境変数が設定されているか確認する
- ポートの空きを確認する：
lsof -i :3600
症状：クライアントが接続できない
考えられる原因：
- ファイアウォールがポート 3600 をブロックしている
- リレーが正しいインターフェースで待ち受けていない
- クライアントのリレー URL が間違っている
対処：
- リレーが動いているか確認する：
docker psまたはhappier relay host status - ファイアウォールを確認する：
sudo ufw allow 3600/tcp - 接続をテストする：
curl http://your-server-ip:3600 - クライアントのリレー URL がサーバーのアドレスと一致しているか確認する
症状：「Authentication failed」エラーが出る
考えられる原因：
- リレーとクライアント登録の間でマスターシークレットが変わった
- 認証トークンを保持せずにリレーを再起動した
対処：
HANDY_MASTER_SECRETが一貫しているか確認する- マスターシークレットを変えた場合はクライアントを再登録する
- リレーのログで認証エラーを確認する
症状：アップデートが反映されない
Docker：
- コンテナを作り直す前にイメージを取得しているか確認する
- イメージのタグが変わっていないか確認する
管理型インストール：
happier relay host installをもう一度実行する- インストール後にサービスを再起動する
よくある質問
セルフホストは必要ですか？
いいえ。ほとんどのユーザーにはクラウドリレーで十分です。
次のような場合はセルフホストしましょう：
- データの保存場所を保証する必要がある
- インフラを完全に管理したい
- コンプライアンス上の要件がある
- 自分で管理するサービスを好む
クラウドからセルフホストに移行できますか？
はい。ただしセッションは自動では移行されません。
手順：
- セルフホストのリレーを用意する
- クライアントが新しいリレー URL を使うように設定する
- 既存のクラウドのセッションはクラウドリレーに残る
- 新しいセッションはセルフホストのリレーを使う
エンドツーエンド暗号化は有効なままですか？
はい。E2E 暗号化はクライアント側で行われ、どのリレーを使うかには左右されません。
リレーの運用者（あなた自身でもクラウド事業者でも）は、どちらにしてもセッションの内容を読めません。
リレーのデータをバックアップするには？
リレーはデータをデータディレクトリに保存します。
Docker： ボリュームのマウントを追加します：
-v /path/to/data:/data管理型インストール：
データの場所は OS によって異なります。happier relay host status で確認してください。
バックアップ：
- リレーを停止する
- データディレクトリをコピーする
- リレーを再起動する
複数のリレーインスタンスを動かせますか？
はい。高可用性や負荷分散のために動かせます。
要件：
- 共有のデータストア（データベース）
- 前段のロードバランサー
- すべてのインスタンスで同じ
HANDY_MASTER_SECRET
クラスタリングの設定は 環境変数のドキュメント を参照してください。