HTTP ゲートウェイ

HTTP ゲートウェイは、同じ Agent を REST/SSE API として公開します。Web アプリ、Slack ボット、カスタムフロントエンドへの Minara 統合に便利です。

サーバーの起動

minara serve
# listening on http://localhost:8080

デフォルトではフォアグラウンドで動作します。Ctrl+C でサーバーを停止できます。フラグ一覧：

-p, --port <N>, 待機ポートを変更します（GATEWAY_PORT の値も参照）。
--auth-token <T>, /v1/* へのすべてのリクエストに必要な Bearer トークンを指定します。GATEWAY_AUTH_TOKEN からも読み込まれます。空にすると auth が無効になります（開発環境専用）。

環境変数：

GATEWAY_PORT（デフォルト 8080）
GATEWAY_AUTH_TOKEN, 設定されている場合、すべてのリクエストに Authorization: Bearer <token> が必要です。空にすると auth が無効になります（開発環境専用）。

Web UI と同時起動

minara serve --ui を実行すると、HTTP ゲートウェイと Web UI が同一シェル内でパラレルプロセスとして起動します。ゲートウェイは 8080 ポート、Web UI は 4173 ポート（apps/web-ui/dist の Vite プレビュービルド）で動作します。

minara serve --ui
# [gateway] listening on http://localhost:8080
# [ui]      preview ready at http://localhost:4173/

コールドブート時の動作：apps/web-ui/dist/ が存在しない場合、または apps/web-ui/apps/agent/src/ より古い場合、Minara はプレビューサーバーを起動する前に自動ビルドを実行します。apps/web-ui/dist/.build.lock 配下のファイルロックにより、複数の serve --ui が同時にビルドで競合することを防ぎます。

バリエーション：

--ui-dev はプレビューの代わりに vite（ホットリロード、ポート 5173）を起動します。Web UI のコードを変更しながら開発する際に使用してください。
--ui-port <N> は UI ポートを上書きします。
--no-build は自動ビルドのチェックをスキップします。apps/web-ui/dist/ がすでに最新の状態であることを前提とします。最新でない場合は即座に失敗します（ゼロ以外の終了コードと明確なエラーメッセージ）。
--daemon は単独の serve --daemon と同様に動作します。ゲートウェイと UI サブプロセスの両方が PID ファイル（server.pid と web-ui.pid）で追跡されます。--stop は PID 再利用ガードを使って両方を終了させるため、無関係なプロセスを指す古い UI の PID ファイルはシグナルを送らずに削除されます。

フラグの全一覧とデーモンの仕組みについては、minara serve サブコマンドリファレンスを参照してください。

デーモンとして実行

--daemon（または -d）を指定すると、サーバーがターミナルから切り離され、PID ファイルが書き込まれ、stdout/stderr がログファイルにリダイレクトされます。systemd を設定せずにゲートウェイを再起動後も継続稼働させたい場合に便利です。

minara serve --daemon              # バックグラウンドで起動
minara serve --status              # 実行中か？ どの PID か？
minara serve --stop                # SIGTERM を送り、最大 10 秒待機

デフォルト値（--pid-file / --log-file で上書き可能）：

PID ファイル：$MINARA_DATA_DIR/server.pid（通常 ~/.minara/server.pid）
ログファイル：$MINARA_DATA_DIR/logs/server.log

終了コードは LSB init-script 規約に従います。デーモンが起動していない場合、--status は 3 を返すため、以下のように連結できます：

minara serve --status || minara serve --daemon

クラッシュ時の再起動、ジャーナル統合、起動時の自動開始など、本番環境レベルのプロセス管理が必要な場合は、minara serve を systemd または任意のスーパーバイザに組み込んでください。サンプルのユニットファイルはデプロイを参照してください。

ヘルスチェック

curl http://localhost:8080/healthz
# {"ok":true}

チャット

curl -N -X POST http://localhost:8080/v1/chat/stream \
  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "buy $50 of SOL"}'

レスポンスは Server-Sent Events ストリームです（-N は curl のバッファリングを無効にします）。各イベントは JSON ペイロードで、LLM の差分出力、ツール呼び出し、最終的なアシスタントの返信が含まれます。

すべてのルート、ペイロード形式、auth フローについては、HTTP API リファレンスを参照してください。

サーバーの起動

Web UI と同時起動

デーモンとして実行

ヘルスチェック

チャット

目次