Entry / Article

Ubuntu Server上のHerdrとCodexを段階的に疎通確認する

2026/9/8 1 min read

Ubuntu Server VMへCodex CLIとHerdrを導入し、Agent認識とSSH切断後の継続を確認しました。TailscaleとMagicDNSでスマートフォンから安全に接続する手順もまとめます。

PVE上のUbuntu Server VMへCodex CLIとHerdrを入れ、SSHを切断してもCodexが残るところまで確認しました。さらにTailscaleを導入し、スマートフォンのモバイル回線からMagicDNS名でSSH接続できるようにしています。

大切だったのは、一度に自動化しなかったことです。Codex単体、Herdrからの認識、SSH切断への耐性、外部回線からの接続を順番に確かめました。問題が起きたとき、原因を絞り込める進め方です。

この記事は3本構成の2本目です。1本目でVMを隔離境界に選び、ここでは手動での疎通を確認します。3本目ではVM起動後の復旧と権限管理を扱います。

検証したCLIはCodex CLI 0.152.0とHerdr 0.8.2です。コマンドや連携仕様は変わるため、導入時にはリンク先の公式資料も確認してください。

CodexとHerdrは別々に導入する

HerdrはCodex本体を含みません。Codex CLIを先にインストールし、ChatGPTアカウントで認証しました。現在のインストールとログイン方法はOpenAI Docsで確認できます。

検証時はnpmでCodex CLIをインストールし、次のコマンドで認証と単体起動を確認しました。

npm install -g @openai/codex
codex login
codex --version
codex

続いてHerdrをインストールし、Herdrが管理するターミナル区画（pane）内でcodexを起動します。通常のSSHシェルで直接起動したCodexは、Herdrの管理対象にはなりません。

herdr

Herdrを開いたら、そのpaneで次を実行します。

codex

Herdrの公式ドキュメントには、インストール方法とQuick Startがまとまっています。今回はmise use -g herdr@0.8.2で導入しました。最終的にはmiseの設定ファイルでNode.js、Codex、Herdrのバージョンを固定する構成へ移しています。

`herdr status`だけではCodexの状態は分からない

最初に戸惑ったのは、herdr statusでサーバーの稼働は分かっても、Codexの状態が見えなかったことです。Agentの確認には別のコマンドを使います。

herdr agent list

この一覧でCodexが認識され、待機状態が取得できることを確認しました。個別の情報を確認する場合は、Agent名を指定します。

herdr agent get <AGENT_NAME>

Agent認識を確認した後、Codex連携もインストールしました。

herdr integration install codex
herdr integration status

連携後は、Herdrが用意したCodex用フックと設定が有効になり、Codexのセッション識別と復元に必要な連携が入りました。Agentの状態判定そのものと同一の機能ではありません。Herdrが対応するAgentと連携の役割は、公式のAgentsとIntegrationsで確認できます。

期待通り、SSHを切っても同じpaneとCodexが残る

CodexをHerdrのpane内で待機させ、SSHを切断してから再接続しました。その後にherdr agent listを実行すると、同じpane IDのCodexがidleとして残っていました。

SSH接続
  ↓
HerdrのpaneでCodexを起動
  ↓
SSH切断
  ↓
再接続
  ↓
同じpaneのCodexを確認

この時点で、SSHを切断してもHerdr配下のプロセスは終了しないことを確認できました。数分かかる処理をSSH切断中も完走できるか、VM再起動後に復元できるかは別の検証です。SSH再接続の成功だけで、再起動耐性まで確認済みとはしませんでした。

TailscaleはまずVPNとして使う

外出先から設定を続けるため、VMとスマートフォンを同じtailnetへ参加させました。Ubuntuへの導入はTailscaleの公式手順に従います。

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
tailscale status
tailscale ip -4

tailscale upが表示する認証URLを開き、VMを登録します。curl | shは取得した内容をそのまま実行するため、必要なら一度ファイルへ保存して内容を確認します。最初からTailscale SSHへ切り替えず、通信路をTailscale、認証を既存のOpenSSHに任せました。変更点を小さくして疎通を優先したためです。

スマートフォン側でもTailscaleを有効にし、Wi-Fiを切ってモバイル回線だけの状態からSSH接続を試しました。最後にMagicDNSを使い、IPアドレスではなく端末名で接続できることを確認しています。

ssh <USER>@<MAGICDNS_NAME>
herdr agent list

これで、スマートフォンからVMへ入り、Herdrが認識するCodexの状態を確認できました。自宅ルーターでSSHポートをインターネットへ公開する必要はありません。ただし、tailnetへの参加だけで安全が保証されるわけではありません。端末承認とアクセス制御を確認し、OpenSSH側でも公開鍵認証を使います。

小さな確認を積み上げる

今回通した確認は、Codex単体の起動、HerdrによるAgent認識、Codex連携、SSH切断後の維持、モバイル回線からのSSH接続です。

VM起動時の自動復旧は、ここから先の課題として切り離しました。手動なら動く状態を先に作ったことで、systemd、Herdr、Codexのどこに問題があるかを判断しやすくなります。常時稼働環境ほど、完成形を一度に作らず、境界ごとに確かめる方が近道でした。