バイナリをインストールして実行する#

すでに opendray バイナリだけを持っている、または欲しいだけで、 インストールウィザードにマシンを触らせたくないという場合のための手順です。この経路は次のケースを対象としています:

• npm install -g opendray / npx opendray — npm パッケージには公式 Go リリースバイナリが同梱されています（README → npm / npx を参照）。
• リリースアーカイブからのダウンロード — リリースページ から opendray_*_<os>_<arch>.tar.gz を取得します。
• スクリプト化・エフェメラル環境 — CI ランナー、ゴールデンイメージ、構成管理（Ansible、Nix、Docker）、または独自の Postgres とプロセススーパーバイザーをすでに運用しているホスト。

バイナリは ゲートウェイそのもの です — web 管理 SPA が埋め込まれているため、Node ランタイムも別の静的サーバーもビルドも不要です。バイナリが しない ことは、何かをセットアップすることです。それがトレードオフです: PostgreSQL データベースとプロセスを動かし続ける手段を自分で用意する代わりに、裏で何かがインストール・設定・登録されることはありません。

すべて自動でやってほしい場合は？ 新しい Linux / macOS マシンなら、ワンラインインストーラーが Postgres のプロビジョニング、AI CLI のインストール、設定の書き込み、サービスの登録まで約 5〜10 分で完了します。README → ワンライナーインストーラー または手動手順の getting-started.md を参照してください。

このガイドでは、「PATH にバイナリがある」状態から「ゲートウェイが動いている」状態まで 5 ステップで到達し、その後サービスとして常駐させる方法を説明します。

ステップ 1 — バイナリを入手する#

npm 経由（Node ≥ 18 の任意の OS）#

適切なプラットフォームバイナリ（opendray-{linux,darwin}-{x64,arm64}）は optionalDependencies 経由で自動的に選択されます — postinstall フックも、 インストール時のネットワーク呼び出しもありません。--no-optional は 渡さないでください: プラットフォームパッケージがスキップされ、ランチャーが実行すべきバイナリを見つけられなくなります。

リリースアーカイブ経由#

確認#

サポート対象プラットフォーム: Linux（x64、arm64）および macOS（x64、arm64）。 ネイティブ Windows はパッケージ化されていません — WSL2 を使用して Linux の手順に従ってください。

ステップ 2 — pgvector 付きの PostgreSQL 15+ を用意する#

opendray はすべて（セッション、メモリ、audit log）を PostgreSQL に保存し、 そのメモリサブシステムには pgvector 拡張が必要です。 サポートされているサーバーバージョン: 15、16、17。

すでに Postgres を運用している場合は、データベースと CRUD のみの role を作成し、 スーパーユーザーで拡張を一度有効にします:

拡張が有効になると、opendray の CRUD のみの role はスーパーユーザーアクセスなしにマイグレーションを実行できます。実行時に opendray をスーパーユーザー role に向けないでください — プロジェクトスコープのアカウントを使用し、パスワードはアウトオブバンドでローテーションしてください。

ステップ 3 — 設定する#

opendray は TOML ファイル または 環境変数のみ（12-factor）から設定を読み込みます — 環境変数は常にファイルより優先されます。唯一の必須要件はデータベース URL で、 それ以外はすべてデフォルト値があります。

オプション A — 環境変数（コンテナ / エフェメラルホスト向け）#

-config フラグなしで opendray serve を実行すると、環境変数のみから読み込みます。

オプション B — config.toml#

最低限編集が必要な箇所:

ロギング、セッションアイドル検出、バックアップ、vault、MCP を含む完全アノテーション付きファイルは config.example.toml を参照してください。以下のコマンドに -config config.toml を渡して使用します。共有ホストでは TOML にシークレットを書かず、 OPENDRAY_DATABASE_URL / OPENDRAY_ADMIN_PASSWORD を環境変数で設定してファイルを非シークレットのままにしてください。

ステップ 4 — スキーマを適用する#

冪等性あり — スキーマが最新であれば再実行しても何も起きません。最初の serve の前に必ず成功させてください。

ステップ 5 — 実行する#

これは フォアグラウンド で実行されます（Ctrl-C で停止）。以下が利用可能になります:

これで完全に動作するゲートウェイです。簡単なテスト以上のことをするなら、 再起動時も存続しクラッシュ時に再起動するよう、スーパーバイザー下で実行しましょう — 次へ。

サービスとして実行する#

opendray serve がまさにサービスユニットの開始コマンドで呼ぶべきものです。 opendray にはハードニング済みのすぐに使えるユニットが同梱されています。以下の手順は README → 本番環境へのデプロイ と同じです。 そちらが権威的なリファレンスです（完全なブートストラップ、サンドボックスのメモ、リバースプロキシ/TLS）。

Linux — systemd#

リポジトリにはハードニング済みのユニットが deploy/systemd/opendray.service として同梱されています （ExecStartPre で migrate を実行、EnvironmentFile 経由でシークレットを渡す、 on-failure での再起動、syscall / ファイルシステムのサンドボックス化）。

systemd がない場合（systemd のない LXC、OpenRC、runit、s6、supervisord…）は、 スーパーバイザーを opendray serve -config /etc/opendray/config.toml に向け、 pre-start ステップとして opendray migrate を一度実行してください。 README → 本番環境へのデプロイ §B を参照してください。

macOS — launchd#

リポジトリには LaunchDaemon が deploy/launchd/com.opendray.opendray.plist として同梱されています （ブート時に起動、クラッシュ時に再起動、/usr/local/var/log/opendray/ にログ出力）。

再起動: sudo launchctl kickstart -k system/com.opendray.opendray。 アンロード: sudo launchctl bootout system/com.opendray.opendray。

両ユニットは完全にドキュメント化されています — シークレットレイアウトや MemoryDenyWriteExecute をオフにしている理由を含めて — deploy/README.md を参照してください。

更新し続ける#

更新方法はインストール方法によって異なります:

• npm 経由でインストール — パッケージマネージャーで更新します。opendray update は npm の管理外で node_modules 内のバイナリを置き換えてしまい、次回インストール時に上書きされてしまうため、ここでは使用しないでください。

  [object Promise]

• リリースダウンロード / ウィザードインストール — バイナリが自己更新します （最新リリースをダウンロードし、SHA-256 を検証してアトミックに置き換えます）:

  [object Promise]

トラブルシューティング#

the matching platform package "opendray-…" was not installed npm が --no-optional で実行されたか、インストールが中断されました。npm install -g opendray を（--no-optional なしで）再実行してください。

unsupported platform npm パッケージがカバーするのは Linux / macOS の x64 / arm64 のみです。その他のターゲットでは ソースからビルドしてください — quickstart.md を参照。

config: database.url is empty OPENDRAY_DATABASE_URL も [database].url も設定されていません。どちらかを設定してください（ステップ 3）。

connection refused (migrate / serve 時) Postgres が起動していないか、DSN が間違っています。サーバーが起動していることと、 DSN 内のホスト / ポート / 認証情報が正しいことを確認してください。

pgvector / extension "vector" is not available 拡張がサーバーにインストールされていないか、opendray データベース内で有効化されていません。 ステップ 2 をやり直してください（OS パッケージをインストールし、スーパーユーザーで CREATE EXTENSION vector を実行）。

Port already in use（ポートが使用中） OPENDRAY_LISTEN（または config.toml の listen）を空きポートに変更してください。

次のステップ#

• README → 本番環境へのデプロイ — 完全なデプロイリファレンス（systemd / launchd / 独自スーパーバイザー、ハードニング、リバースプロキシ）
• docs/operator-guide.md — 運用: リバースプロキシ/TLS トポロジー、暗号化 DB バックアップ、データのエクスポート / インポート
• docs/integration-guide.md — REST + WebSocket API を使った外部連携の構築
• docs/getting-started.md — 構成要素を自分で組み立てたくない場合のガイド付きオールインワンセットアップ