ガイド

MacでDockerを使ってHermes Agentをインストールする方法

2026年5月18日

このガイドでは、Mac上でDocker Desktopを使い、公式DockerイメージからHermes Agentを実行する流れを説明します。ローカルのPython環境を直接いじらず、コンテナ内でHermes Agentを動かしたい場合に向いた方法です。

モデル接続にはAPI key方式もありますが、ここではChatGPT OAuthを使ったOpenAI Codex providerを中心に扱います。順番は、Docker Desktopの準備、setup wizard、provider設定、Hermes Agentの起動、そしてlocalhost:9119のDashboard確認です。

要点

まずMacにDocker Desktopをインストールして起動する。
公式イメージはnousresearch/hermes-agentを使う。
~/.hermesを/opt/dataにマウントし、設定、OAuthトークン、セッション、Skills、ログを保持する。
最初にsetupを実行し、その後hermes modelでOpenAI Codex providerを選ぶ。
Dashboardを有効にしたGatewayではhttp://localhost:9119に接続できる必要がある。

必要なもの

必要なもの	説明
Mac	Apple SiliconとIntel Macの両方で使えるが、Docker Desktopはチップに合うものを選ぶ。
Docker Desktop	Hermes Agentコンテナを実行するために必要。
Terminal	Dockerコマンド、setup、OAuth、ログ確認に使う。
ChatGPTアカウント	OpenAI Codex providerをChatGPT OAuthで接続するために使う。
インターネット接続	Dockerイメージの取得とOAuthログインに必要。

Mac、Docker Desktop、Hermes Agentコンテナ、永続データVolumeを示す図 — DockerがHermes Agentを実行し、`~/.hermes`がMac側にデータを保存する。

Docker方式の意味

Hermes AgentはNousResearchが公開しているAI agent runtimeです。公式ドキュメントでは、local installation、Docker execution、Docker terminal backendなど複数の使い方が説明されています。この記事では、Hermes Agent本体をDockerコンテナ内で動かす方法に絞ります。

Docker方式では、Python、Node.js、browser automation dependenciesなどをmacOSへ直接入れずに済みます。一方で、Docker Desktopが先に起動している必要があり、ファイルアクセスは明示的にmountしたフォルダを通じて考える必要があります。

Hermes Agentではコンテナ内のユーザーデータ場所として/opt/dataを使います。そのため、Mac側の~/.hermesを/opt/dataへ接続します。

Docker Desktopをインストールする

Docker公式のMac向けインストールページからDocker Desktopをダウンロードします。M1以降のMacならApple Silicon版、古いIntel MacならIntel版を選びます。

基本の流れは次の通りです。

Docker公式のMac向けインストールページからDocker Desktopをダウンロードする。
Docker.dmgを開き、DockerをApplicationsフォルダへ移動する。
ApplicationsからDocker Desktopを起動する。
初回の権限確認や利用条件を確認する。
メニューバーのDockerアイコンが安定して準備完了になるまで待つ。

その後、Terminalで確認します。

docker --version

コマンドが見つからない場合は、Docker Desktopがまだ起動していないか、CLI連携が完了していない可能性があります。

Docker DesktopをインストールしてTerminalでdocker versionを確認する流れ — Hermes Agentを起動する前に、Docker CLIがTerminalから使えることを確認する。

`~/.hermes`をマウントする理由

DockerでHermes Agentを使うとき、Volume Mountは省略しない方がよい重要な設定です。これがないと、コンテナを消したときに設定やログイン状態も失われやすくなります。

すべてのHermesコマンドで同じマウントを使います。

-v ~/.hermes:/opt/data

Macの~/.hermesフォルダがDockerコンテナ内の/opt/dataに接続される図 — `~/.hermes:/opt/data`により、設定、セッション、OAuth情報、Skills、ログを保持できる。

初回実行: setup wizardを起動する

データフォルダを作り、公式のsetupを実行します。

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

--rmによりコンテナ自体は終了後に削除されますが、/opt/dataに作成された内容はMac側の~/.hermesに残ります。

setup wizardでは、バージョンによって次のようなファイルやフォルダが作成または更新されます。

場所	役割
`~/.hermes/.env`	API key方式のproviderを使う場合のsecretを保存する。
`~/.hermes/config.yaml`	モデル、backend、gateway、tool設定を保存する中心ファイル。
`~/.hermes/SOUL.md`	Agentの基本的な振る舞いや方針を記述する。
`~/.hermes/sessions/`	セッション履歴を保存する。
`~/.hermes/memories/`	長期記憶データを保存する場合がある。
`~/.hermes/skills/`	インストールされたSkillsを保存する。
`~/.hermes/logs/`	実行ログを保存する。

実際の質問はHermes Agentのバージョンによって変わりますが、初心者は次の方針で進めると安全です。

setupの質問	実用的な選択
Model provider	`OpenAI Codex`または`Codex`系の項目を選ぶ。見つからない場合はsetupを終えてから`hermes model`を実行する。
Authentication method	API key providerは`.env`に値を保存する。ChatGPT OAuthは`auth.json`のようなauth storeにtokenを保存する。
Chat system / gateway integration	Telegram、Discord、Slackをすぐ使わないなら後で設定してよい。gatewayを常時使う予定ならここで設定してもよい。
よく分からないdefault	まずdefaultのまま進め、動作確認後に`config.yaml`を調整する。

つまり、setupでは基本ファイルとフォルダを作り、provider選択が分かりにくければ後からhermes modelで開き直す流れが扱いやすいです。

setup後は以下で確認します。

ls -la ~/.hermes

config.yamlが存在することも確認します。ファイル全体を公開せず、ローカルで冒頭だけ見る程度にします。

sed -n '1,80p' ~/.hermes/config.yaml

.envにはsecretが含まれる可能性があるため、内容を共有しないでください。存在確認だけなら次のようにします。

ls -la ~/.hermes/.env

setupが完了したのに~/.hermes/config.yamlがない、またはフォルダが空の場合は、まずVolume Mountを確認してください。コマンドに-v ~/.hermes:/opt/dataが必要です。

ChatGPT OAuthを設定する

setupでprovider設定を終えていない場合は、model pickerを開きます。

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent model

OpenAI CodexまたはCodex系の項目を選びます。URLやdevice codeが表示されたら、Macのブラウザで開いてChatGPTアカウントでログインします。

バージョンによっては、次のcredentialコマンドも使えます。

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

OAuth tokenは使い捨てコンテナの中だけに置くものではありません。auth.jsonのようなauth storeとして、mountされた~/.hermes配下に保存されます。これにより、コンテナを作り直しても同じprovider設定を維持できます。

ブラウザのChatGPT OAuthログインとHermes Agent Dockerコンテナの接続を示す図 — ChatGPT OAuthでは、OpenAI API keyをコマンドに貼り付けずにOpenAI Codex providerを接続できる。

Hermes Agentを実行する

setupとprovider設定が終わったら、Hermes Agentを対話モードで起動します。

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

対話セッションが開けば、基本的なインストールは成功しています。以後も同じVolume Mountを使います。

各optionの意味は次の通りです。

Option	意味
`docker run`	新しいcontainerを起動する。
`-it`	対話的なterminal sessionを開く。
`--rm`	終了後に一時containerを削除する。
`-v ~/.hermes:/opt/data`	Macの`~/.hermes`をcontainer内の`/opt/data`へ接続する。
`nousresearch/hermes-agent`	公式Hermes Agent Docker imageを使う。

`localhost:9119`でDashboardを確認する

setup、provider設定、対話起動が動いたら、imageとversionを確認します。

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

OAuth providerの状態は、同じdata folderをmountして確認します。

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth list

GatewayとWeb Dashboardをバックグラウンドで動かす場合は、両方のポートを公開します。

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Macのブラウザでhttp://localhost:9119を開きます。http://127.0.0.1:9119でも確認できます。Dashboardは設定、セッション、ログ、Skillsを確認するためのローカル管理画面です。

開けない場合は応答とログを確認します。

curl -I http://127.0.0.1:9119

runtimeの詳細はlogsで確認します。

docker logs --tail 50 hermes

Dashboard関連のログには[dashboard]が付くことがあります。

background containerを止めて削除する場合は次の通りです。

docker stop hermes
docker rm hermes

よくある問題

症状	確認すること
`Cannot connect to the Docker daemon`	Docker Desktopが起動しているか確認する。
`docker: command not found`	Docker CLIがTerminalで使える状態か確認する。
OAuth URLが開かない	コンテナに表示されたURLやdevice codeをブラウザへコピーする。
OpenAI Codex providerが見えない	最新のHermes Agent imageをpullし、`hermes model`メニューをもう一度確認する。
設定が消える	`-v ~/.hermes:/opt/data`が抜けていないか確認する。
Permission error	現在のmacOS userが`~/.hermes`へ書き込めるか確認する。
Dashboardが開かない	`-p 9119:9119`、`-e HERMES_DASHBOARD=1`、`[dashboard]`ログを確認する。
ポート衝突	`8642`または`9119`を別プロセスが使っていないか確認する。

Apple Silicon Macでは、Intel専用imageを強制しない限りDocker Desktopがarchitecture差を処理することが多いです。まずは公式のlatest imageと最新のDocker Desktopから始めてください。

Docker状態、OAuth、Volume Mount、ログ、Dashboardを順に確認する流れ — Docker、OAuth、Volume Mount、ログ、Dashboardポートの順に確認すると原因を絞りやすい。

更新と削除

更新するときは新しいイメージを取得し、~/.hermesを残したままコンテナを作り直します。

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

コンテナとイメージを削除する場合は次の通りです。

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

~/.hermesを削除すると、設定、OAuthトークン、セッション、Skills、ログも消えます。

rm -rf ~/.hermes

まとめ

安定した手順は、Docker Desktopを入れる、setupを実行する、OpenAI CodexをChatGPT OAuthで接続する、~/.hermesを/opt/dataにマウントする、Gateway利用時にhttp://localhost:9119を確認する、という流れです。