ソースからのインストールへ切り替える

1. バックアップを取り、古い実行環境を止める
2. 独立したチェックアウトをクローンする
3. ソース版の実行環境を準備する
4. 使うデータを意図して選ぶ
Docker を使っている場合
Nix や Termux を使っている場合
ダウングレードが安全だと決めつけずに元へ戻す
困ったときは

ソースのチェックアウトとパッケージ版のアプリは、別々のインストールです。パッケージ版のアプリは同梱された中身を使い続け、近くにあるチェックアウトに乗り換えることはありません。手を加えたコードを GUI で動かしたいときは、ソースからビルドしたデスクトップ版を使います。

ユーザーデータは通常、アプリの外に置かれています。

環境	データの既定の場所
Linux、macOS、WSL、Termux	`~/.hermes/`
ネイティブの Windows	`%LOCALAPPDATA%\hermes\`
公式の Docker コンテナ	`/opt/data/`（ホスト側のストレージに対応づけたもの）

HERMES_HOME と選んだプロファイルによって、これらの既定値は変わることがあります。インストールを切り替える前に、切り替え元と切り替え先で実際に使うホームディレクトリを書き留めておいてください。

1. バックアップを取り、古い実行環境を止める

いまのインストールで、次を実行します。

hermes backup
hermes gateway status

バックアップは、削除する予定のディレクトリの外に保管してください。バックアップには認証情報が含まれることがあるので、それに見合った管理をしてください。

引き継ぐ前に、デスクトップ版を終了し、自分が動かしているゲートウェイやサービスを止めます。デスクトップ版の終了と hermes gateway stop は別の操作です。アプリを終了しても、別に管理されているメッセージングゲートウェイが止まるとは限りません。

プロファイルごとのゲートウェイのロックによって、ゲートウェイが重複して起動することは防がれます。セッションのロックと SQLite の同時アクセスは別の話です。2 つ目のプロセスを起動しただけで SQLite のジャーナルモードが切り替わるわけではありません。引き継ぎの間は、どちらかのバージョンがデータの移行をしている最中に、異なるバージョンのコードが同じホームへ書き込む状態を避けてください。

2. 独立したチェックアウトをクローンする

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

開発に使う場合は、代わりに自分のフォークをクローンし、本家のリポジトリを upstream として追加します。依存パッケージを準備する前に、使うブランチかコミットを選んでください。署名済みのアプリのパッケージの中へクローンしたり、パッケージ版の実行環境を上書きしたりしないでください。

3. ソース版の実行環境を準備する

ネイティブのビルドに必要な前提条件と、現時点でのブートストラップの制限は、開発の流れをご覧ください。準備の前に使う HERMES_HOME を決めてから、環境を有効化します。有効化するとブートストラップ自体が実行されます。

source ./activate
hermes --version

ネイティブの Windows では PowerShell を使います。

. .\activate.ps1
hermes --version

ブートストラップは pm/lock.json からツールの固定バージョンを読み取り、インストールを PM に任せます。現在の公式のコードは Python 3.14 で動きます。パッケージのメタデータにある広めの >=3.11,<3.15 は、古いインストールでもアップデーターを動かせるようにして、 PM が 3.14 へ切り替えるまでをつなぐためだけのものです。実行環境として対応する範囲ではありません。ソース版の既定は all extra で、デスクトップ版パッケージの --all-extras とは違います。

有効化すると、インストール済みのツール環境が組み込まれ、hermes がこのワークツリーの CLI として定義されます。この関数は古い hermes コマンドや MSIX のエイリアスより優先され、ワークツリーの外では実行を拒否します。作業を終えたら deactivate で、シェルの環境が元に戻り、関数も取り除かれます。

テスト用の依存パッケージや手動の環境については、開発環境のセットアップをご覧ください。選ばれる Python の世代と、書き込めるツール置き場についてはパッケージ管理をご覧ください。

4. 使うデータを意図して選ぶ

同じ端末で普段どおり使うなら、前のインストールと同じ HERMES_HOME とプロファイルを選びます。開発に使うなら、新しいコードが保存済みのデータを移行することがあるので、別のホームを使うほうが安全です。

POSIX の例:

export HERMES_HOME="$HOME/hermes-source-data"
hermes setup
hermes

PowerShell の例:

$env:HERMES_HOME = Join-Path $HOME 'hermes-source-data'
hermes setup
hermes

PM の状態を準備したあとでホームを変えた場合は、そのホームに対してブートストラップを実行してから、そこで選ばれた依存パッケージを使ってください。環境変数を変えただけで、データが移ったり実行環境の状態がコピーされたりするわけではありません。

ソース版のデスクトップアプリをビルドするには、準備済みのチェックアウトで hermes desktop を実行します。古いパッケージ版のアプリを開くと、そのパッケージに同梱されたバックエンドが起動します。

Docker を使っている場合

/opt/data はコンテナ内のパスで、ホスト側からそのまま使えるパスとは限りません。バインドマウントの場合は、ホスト側のディレクトリをソース版プロセスの HERMES_HOME にします。名前付きボリュームや Docker Desktop の VM 内ストレージの場合は、まず古いゲートウェイを止めます。そのうえで、バックアップをエクスポート / インポートするか、管理されたマウントを通してデータをコピーします。コピー先の所有者と権限も確認してください。

ローカルで docker build -t hermes-agent . を実行すると、イメージで管理される別のインストールができるだけです。動いているコンテナが、自分で更新できるソースのチェックアウトに変わるわけではありません。そのイメージを使うには、コンテナを作り直してください。Docker をご覧ください。

Nix や Termux を使っている場合

ローカルで nix run . を実行しても、動くのは Nix が管理する derivation のままです。パッケージのファイルは書き換えられず、更新も Nix の担当のままです。開発用のシェルには nix develop を使うか、環境が対応していれば上で説明したソースからの手順を使ってください。

Termux 向けの配布物は、bionic 用の APT パッケージです。デスクトップ / サーバー向けのソースのブートストラップは、Termux で開発や修復に使う手段としてはサポートされていません。パッケージとビルドの扱いの範囲は Termux のガイドをご覧ください。

ダウングレードが安全だと決めつけずに元へ戻す

ソース版の実行環境を止め、有効化した環境から抜けてから、パッケージ版のアプリを開きます。もう一度 hermes を使う前に、どの CLI コマンドが呼ばれるかを確かめてください。

command -v hermes

Windows では Get-Command hermes -All を使います。持ち主を確かめずに、無関係なコマンドやアプリ実行エイリアスを置き換えないでください。

新しいソースのリビジョンでは、データの形式が変わることがあります。古いパッケージに戻すことは、スキーマの移行を元に戻すこととは違います。いまのデータは残したうえで、古いパッケージがそれを必要とするなら、切り替え前に取っておいた互換性のあるバックアップを復元してください。

ソースのチェックアウトを削除しても、パッケージ版のアプリは消えません。また、PM のツールの登録や Python の世代が、すべて自動で片付くわけでもありません。共有のデータのルートディレクトリを削除するのではなく、 PM の診断機能とガベージコレクションを使ってください。

困ったときは

バージョンが違う: どのコマンドが呼ばれているかを確かめてから、有効化したチェックアウトで

hermes --version を実行します。

依存パッケージが足りない: 使うつもりのソースの環境で python -m pm.cli install を実行し、

影響を受けた Hermes のプロセスを再起動します。

ゲートウェイがすでに動いている: 選んでいるプロファイルについて hermes gateway status を

確認します。特定できた持ち主を止め、無関係なプロセスは終了させないでください。

初回起動後にスキルが変わっている: 新しいコードは、同梱のスキルをデータのホームへ同期することがあります。

ソースのチェックアウトは、そのホームを読み取り専用で見せるものではありません。