hostpanel

hostpanel

hostpanel は、Docker デーモンとコンテナーの状態、Compose プロジェクト、基本的なホスト情報、ファイル検索、ZFS プール、ジャーナルログなど、単一のホストを管理します。これらすべてを、2 つのアクションルーターツール flux と scout、およびコマンドライン上の同じ 2 つのルーターを通じて提供します。1 つのバイナリでどちらの用途にも対応します。

これは、より大きなドキュメント化された機能範囲から切り出した、ラベル付きのコアサブセットです。実装されているアクションは以下に記載されています。このサブセットから除外された、ドキュメント化済みのその他のアクションは、黙って削除されるのではなく、ビルドレポートと仕様フィクスチャーに記載されています。

提供対象はローカルホストのみです。host パラメーターを指定する場合は local でなければなりません。リモート SSH 接続先はこのサブセットの対象外です。プロセスは引数配列のみで起動されます。コマンド文字列がシェルを経由することはありません。

インストール

npx @reneturcios/hostpanel help

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/hostpanel

コンテナーはデフォルトで MCP サーバーとして動作します（以下を参照）。代わりに CLI として使用するには CLI 引数を渡し、flux アクションから実際のデーモンにアクセスする場合は Docker ソケットをマウントしてください。

CLI

hostpanel flux docker info
hostpanel flux docker version
hostpanel flux container list --params '{"state":"running"}'
hostpanel flux container inspect --params '{"container_id":"abc123"}'
hostpanel flux host info
hostpanel flux compose list

hostpanel scout nodes
hostpanel scout exec --params '{"command":"hostname"}'
hostpanel scout exec --params '{"command":"cat","args":["/etc/hostname"]}'
hostpanel scout find --params '{"path":"/srv","pattern":"*.log","limit":20}'
hostpanel scout zfs pools
hostpanel scout logs journal --params '{"unit":"docker","lines":50}'

hostpanel help
hostpanel --version

成功した呼び出しでは、実行した argv と、取得した stdout、stderr、exitCode を含む JSON オブジェクトが出力されます。nodes アクションと help アクションは、ローカルで回答を直接出力します。終了コードは次のとおりです。成功時は 0、呼び出し失敗時（拒否されたコマンドや、子プロセスの終了コードが 0 以外の場合を含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/hostpanel mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "hostpanel": {
      "command": "npx",
      "args": ["-y", "@reneturcios/hostpanel", "mcp"]
    }
  }
}

ツール

どちらのツールも、必須の action、任意の subaction、任意の params オブジェクトを受け取ります。params 内のパラメーター名は、各アクションの元の表に従います（host、container_id、state、name_filter、image_filter、label_filter、path、pattern、depth、limit、command、args、pool、lines、unit、priority、since、until、grep）。

ツール	アクション	サブアクション	機能
flux	docker	info	Docker デーモン情報（docker info）。
flux	docker	version	Docker のバージョン（docker version）。
flux	container	list	コンテナーの一覧表示（docker ps）。状態、名前、イメージ、ラベルで任意に絞り込めます。
flux	container	inspect	1 つのコンテナーを調査します（docker inspect）。container_id が必須です。
flux	host	info	OS、カーネル、アーキテクチャー（uname -a）。
flux	compose	list	Compose プロジェクトの一覧表示（docker compose ls）。
flux	help	—	ローカルで回答する flux アクションのリファレンス。
scout	nodes	—	設定済みホスト。このサブセットでは local のみです。
scout	exec	—	許可リストにある読み取り専用コマンドを 1 つ実行します。command が必須で、args は任意です。
scout	find	—	glob でファイルを検索します（find <path> -name <pattern>）。path と pattern が必須です。
scout	zfs	pools	ZFS プールの一覧表示（zpool list）。pool で任意に絞り込めます。
scout	logs	journal	systemd ジャーナルを読み取ります（journalctl）。行数、ユニット、優先度、開始日時、終了日時、grep で任意に絞り込めます。
scout	help	—	ローカルで回答する scout アクションのリファレンス。

exec の許可リスト

scout exec は読み取り専用の検査コマンドのみを実行します。許可リストには、cat、head、tail、grep、rg、ls、tree、wc、uniq、diff、stat、file、du、df、pwd、hostname、uptime、whoami の 18 個のコマンドがすべて含まれます。それ以外のもの（git、シェル、インタープリター、変更を加えるツールなど）は、プロセスが起動する前に拒否されます。コマンドは単一の名前でなければなりません。引数は個別に args 配列で渡され、シェル文字列に補間されることなく argv として渡されます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake executor only
npm run dev     # run the CLI from source via tsx

テストでは偽のエグゼキューターを注入するため、各アクションが実行する argv を記録し、拒否されたコマンドがエグゼキューターに到達しないことを検証します。Docker デーモン、ZFS プール、ジャーナルは不要です。また、テストスイートはホスト上で実際に得られた結果を主張しません。

ライセンス

MIT — LICENSE を参照してください。