Helmdeck

helmdeck

本日、helmdeck のインストールでは gpt-oss-120b を使って、コード編集の一連の作業を6段階（クローン、読み込み、パッチ適用、テスト、コミット、プッシュ）まで完了し、費用は $0.07 でした。同じ作業を Cursor または Claude Code から Sonnet を直接使って行うと、$0.30 以上かかります。同じ結果を約5分の1の費用で実現できます。しかも、「高価な」構成が最も高価な選択肢というわけでもありません。

ワークフロー	最先端モデルを使う方法	Helmdeck（gpt-oss-120b）
ブラウザーでのスクレイピング＋GitHub コメント	$0.25（Anthropic Computer Use）	$0.005
コード編集ループ（6段階）	$0.35（Cursor / Aider）	$0.07
複数ステップのブラウザーテスト	$0.20（Browser-use NL）	$0.03
PDF → 構造化 Markdown	$1.00（単純な Sonnet ビジョン）	$0.003

多くのブラウザーエージェントは、安定して動作させるために GPT-4o または Claude Sonnet を必要とします。 Helmdeck は、導入の残り99％、すなわち ローカルの7Bモデル、エアギャップ環境、認証情報をクラウド API に送信できないチーム向けに構築されています。ブラウザー、デスクトップ、git、コードのあらゆる操作を、規模の小さなモデルでも正しく値を設定できる、単一の型付き JSON 呼び出しにまとめます。 上記の数値は、その結果です。パックが、LLM が再発見するためにトークンを消費するはずの作業を担うことで、低価格モデルやローカルモデルでも、最先端モデルの API なら10倍の費用がかかるエージェント型の作業を実行できます。

セルフホスト可能なコンテナ化プラットフォームです。AI エージェント向けに、スキーマ検証済みの単発 JSON ツールである Capability Pack とネイティブ MCP を提供します。最も重視する指標は、オープンウェイトの7B～30Bクラスのモデルでパック成功率90％以上を達成することです。最先端モデルを対象とする競合で、これを最適化しているものはありません。

📊 https://helmdeck.dev/explanation/why-helmdeck で、再現手順付きのタスクごとの詳細な比較をご覧いただけます。これらはメンテナー1人による調査結果です。コミュニティでの再現検証も歓迎します。

これが存在する理由

高性能なモデルは bash と README があれば力を発揮しますが、性能の低いモデルは自由度の高いインターフェースで行き詰まります。Helmdeck は、ブラウザーセッション、デスクトップ操作、認証情報、複数ステップのワークフローを、型付きの単一 REST / MCP 呼び出しの背後に隠すことで、その差を埋めます。

特に、次の3つの利用者を想定しています。

• セルフホスト型 AI チーム：VPC の外に出られず、外部に通信しない MCP ネイティブなインフラを必要とするチームです。
• LocalLLaMA / Ollama のユーザー：7B～30Bモデルを実行しているユーザーです。パックの契約により、自由度の高いツールでは失敗する場面でも、小規模モデルの信頼性を保てます。
• セキュリティを重視する組織：モデルに認証情報を一切見せずに、エージェントから SaaS アプリにログインさせる必要がある組織です（ボールト連携のプレースホルダートークン＋MCP レベルの監査）。

ステータス

v0.22.0 をリリースしました — 無料モデルで動作し、メモリを備えたエージェントです。 このリリースでは ADR 047〜050 が完了しました。

• パイプラインルーティング＋ルーティングメモリ（ADR 047） — helmdeck.route メタパックが、インテントに最適なパック／パイプラインを推奨します（適合するものがない場合は、構造化された不足警告を表示します）。呼び出し元ごとに学習したデフォルト設定を基盤とし、helmdeck://routing-guide と helmdeck://my-defaults の MCP リソース、およびルーティングメモリ管理 UI を通じて利用できます。
• メモリ書き込み機能＋OpenClaw ブリッジ（ADR 048） — helmdeck.memory_store が永続的なユーザー情報を保存し（helmdeck://my-memory から読み戻せます）、オプションの埋め込みサイドカーが OpenClaw の memory_search を強化します。また、QMD コーパスブリッジによって、helmdeck のメモリを OpenClaw に公開します。
• インテントの分解（ADR 049） — helmdeck.plan が、複数のアクションを含むプロンプトを、順序付けられたパイプライン対応のステップ計画と rewritten_prompt に変換します。
• LLM コンテキストマネージャー（ADR 050） — internal/llmcontext が、カタログ情報を多く含むプロンプトを小型モデルのコンテキスト予算に収まるように圧縮します（モデルごとの段階的な予算、カスケード式選択＋語彙順位付け、オプションの 2 パスフィルター）。helmdeck://context-budgets と helmdeck://my-plans を通じて利用できます。

コントロールプレーンのバイナリには 57 個の機能パック が同梱されています（AI ゲートウェイ未設定の場合は 47 個）。これに加えて、21 個の組み込みパイプライン、コミュニティパックのマーケットプレイス（helmdeck pack install <name>）、およびオペレーターが提供する cmd.* サブプロセスパックを利用できます。これまでの主な機能も引き続き利用できます。コンテンツのエンドツーエンドの連携（image.generate が podcast／slides／blog のカバー画像に自動的に内容を渡す機能）、helmdeck://image-models MCP リソース、イメージモードでのインストール（./scripts/install.sh --image-mode）、Pack Test Runner UI などです。Helmdeck は 公式 MCP Registry に io.github.tosin2013/helmdeck として公開されており、レジストリ対応クライアントから 1 行でインストールできます。フェーズ 1〜6.5 は完了しており、現在のマイルストーンは v1.0 — Kubernetes と GA（フェーズ 7）です。バックログは、GitHub の good first issue および help wanted ラベル付きの Issue として登録されています。

• docs/adrs/ に 49 件の ADR — PRD への参照を含む、すべてのアーキテクチャ上の決定事項
• docs/TASKS.md に タスクの内訳 — 8 フェーズにわたる約 85 件のタスクとクリティカルパス
• docs/MILESTONES.md に GitHub マイルストーン — 現在のリリース状況を含む、そのまま使える Issue チェックリスト
• docs/PACKS.md に パックのリファレンス — リリース済みパックすべての入力／出力コントラクト

クイックスタート

git clone https://github.com/tosin2013/helmdeck
cd helmdeck
./scripts/install.sh

これで完了です。スクリプトはプラットフォームに応じたインストール方法を提示しながら、事前チェック（docker、node ≥20、go ≥1.26、make、openssl、curl）を実行し、新しいシークレットを deploy/compose/.env.local に生成して（chmod 600）、Management UI バンドル、Go バイナリ、ブラウザーサイドカーイメージをビルドします。その後、Compose スタックを起動し、URL と新たに生成された管理者パスワードを表示します。

✓ helmdeck is up

  URL:       http://localhost:3000
  Username:  admin
  Password:  <generated; printed once — save it now>

便利なフラグ：

• ./scripts/install.sh --reset — スタックを停止し、シークレットを再生成して再インストールします（管理者パスワードが新しくなります）
• ./scripts/install.sh --no-build — ビルド手順を省略し、スタックだけを起動します
• ./scripts/install.sh --help — すべてのフラグのリファレンスを表示します

または make を使用します：make install。

クライアントを接続する

スタックを起動しただけでは、プラットフォームが用意されたにすぎません。価値を生み出すのは、エージェントが呼び出すパックです。新しくインストールした環境に、サポート対象の MCP クライアントを接続してください。

クライアント	状況	セットアップガイド
OpenClaw	✅ エンドツーエンドで検証済み	docs/integrations/openclaw.md
Claude Code	🟡 ドキュメントあり	docs/integrations/claude-code.md
Claude Desktop	🟡 ドキュメントあり	docs/integrations/claude-desktop.md
Gemini CLI	🟡 ドキュメントあり	docs/integrations/gemini-cli.md
Hermes Agent	🟡 ドキュメントあり	docs/integrations/hermes-agent.md

クライアントを接続したら、pack-demo-playbook.md に沿って進めてください。すべてのパックを試せる、コピーしてそのまま使えるプロンプトが20個以上あります。パックごとのリファレンスでは、各パックの契約、エラーコード、連鎖するワークフローについて説明しています。

上級者向け：手動セットアップ

インストールスクリプトを実行する代わりに、各手順を自分で進めたい場合：

# 1. Build the Management UI bundle (needs Node 20+)
make web-deps && make web-build

# 2. Build the control-plane binary with the UI embedded
make build

# 3. Run the control plane with admin credentials
HELMDECK_JWT_SECRET=$(openssl rand -hex 32) \
HELMDECK_VAULT_KEY=$(openssl rand -hex 32) \
HELMDECK_ADMIN_PASSWORD=changeme \
./bin/control-plane

または、Compose スタックを直接使用します（コントロールプレーン＋Garage オブジェクトストア＋同梱の初期化処理）：

cp deploy/compose/.env.example deploy/compose/.env.local
# …edit deploy/compose/.env.local and fill in real secrets…
docker compose -f deploy/compose/compose.yaml --env-file deploy/compose/.env.local up -d

管理 UI へのログイン

ログインエンドポイントでは、コントロールプレーンのプロセスで設定する HELMDECK_ADMIN_PASSWORD 環境変数を使って、静的な管理者パスワードを設定できます。開発環境／単一ノードの Compose 環境に適しています。本番環境向けの OIDC SSO は、後のフェーズで導入される予定です。

設定	デフォルト	上書き方法
ユーザー名	admin	HELMDECK_ADMIN_USERNAME 環境変数
パスワード	(なし — UI ログインは無効)	HELMDECK_ADMIN_PASSWORD 環境変数（必須）
セッション期間	12 時間	internal/api/auth_login.go にハードコード

パスワードを変更するには： コントロールプレーンを停止し、HELMDECK_ADMIN_PASSWORD に新しい値を設定してから再起動してください。現在、UI 上でパスワードを変更する機能はありません。パスワードは、コントロールプレーンを実行するオーケストレーター（Compose、systemd、Kubernetes Secret など）によって、UI の外部で管理します。

HELMDECK_ADMIN_PASSWORD が未設定の場合、ログインエンドポイントは 503 login_disabled を返します。コントロールプレーンは引き続き実行され、API も引き続き利用できます。運用担当者は、CLI から直接 JWT を発行できます。

./bin/control-plane -mint-token=alice -mint-token-scopes=admin -mint-token-ttl=12h

発行したトークンは、Authorization: Bearer <token> に対応する任意のツールに貼り付けて使用できます。

本番環境に関する注意： 静的パスワード方式では、タイミング攻撃への対策として定数時間比較を使用しています。ただし、手動でローテーションする必要がある共有シークレットであることに変わりはありません。複数の運用担当者がいる本番環境では、既存の ID プロバイダーを利用した OIDC SSO が適切な選択肢です。Phase 6 のフォローアップロードマップを参照してください。

アーキテクチャの概要

• サイドカーパターン — ブラウザーは独立したコンテナーで実行され、エージェントには組み込まれません（ADR 001）
• Golang コントロールプレーン — 単一の静的バイナリーで、distroless イメージを使用し、React UI を内包します（ADR 002）
• Capability Packs — 主要な製品機能です。Go または WASM でユーザーが作成できます（ADR 003、012、024）
• OpenAI 互換 AI ゲートウェイ — 暗号化されたキーとフォールバックルーティングに対応し、Anthropic、Gemini、OpenAI、Ollama、Deepseek を利用できます（ADR 005）
• MCP サーバーのレジストリ — stdio／SSE／WebSocket トランスポートに対応します。組み込み MCP サーバーはパックカタログから自動生成されます（ADR 006）
• 認証情報保管庫 — AES-256-GCM とプレースホルダートークンの挿入を使用します。エージェントがシークレットを参照することはありません（ADR 007）
• 2 層のデプロイ方式 — 開発環境／単一ノードには Docker Compose、本番環境の Kubernetes には Helm チャートを使用します（ADR 009、010、011）
• MCP クライアントを第一級でサポート — 単一の共有 helmdeck-mcp ブリッジバイナリーを介して、Claude Code、Claude Desktop、OpenClaw、Gemini CLI を利用できます（ADR 025、030）
• オブジェクトストアを同梱 — Garage は Compose スタックにデフォルトのアーティファクトバックエンドとして含まれています。本番環境では、S3 互換の任意のエンドポイント（AWS S3、R2、B2、SeaweedFS）に接続できます（ADR 031）

組み込み機能パック

57 個のパックが標準で付属しています（AI ゲートウェイを設定していない場合は 47 個）。それぞれが複数の手順からなるワークフローを、型付きの単一の JSON Schema 呼び出しの背後に隠しているため、性能の低いオープンウェイトモデルでも、最先端モデルと同じように確実に実行できます。各パックの入出力仕様の完全版は docs/PACKS.md にあります。主なパックは次のとおりです。

パック	内包する処理
ブラウザーとウェブ
browser.screenshot_url	セッションのライフサイクル、ナビゲーション、レンダリング待機、クリーンアップ
browser.interact	決定論的な複数手順の CDP（navigate、click、type、scroll、screenshot、assert_text）— LLM 不要
web.scrape / web.scrape_spa	Firecrawl を利用した Markdown スクレイピング、またはスキーマ駆動の SPA 抽出
web.test	Playwright MCP と LLM のループによる自然言語のブラウザーテスト
research.deep	複数の情報源を対象にした Firecrawl 検索、情報源ごとのスクレイピング、インライン引用付きの LLM による統合
content.ground	Markdown ファイルから主張を解析し、信頼できる情報源を探して、該当箇所に実際の [link](url) 引用を挿入
ドキュメントとビジョン
slides.render	Marp + Chromium + フォーマットフラグ
slides.narrate	ナレーション付き MP4 動画（スライドごとの ElevenLabs TTS）+ YouTube エンゲージメントメタデータ + サイドカー SRT 字幕 + 構造化された validation フィールド（デフォルトで有効な後処理ステップ）
av.validate	AV アーティファクトの構造化検証（faststart、コーデックの固定、パケットの連続性、RMS スイープ、LUFS、再生時間の一致、SRT 形式）。slides.narrate／podcast.generate の後処理ステップとしてデフォルトで有効。必要に応じたチェックには単独でも使用可能
doc.parse	レイアウトを考慮した Docling 解析 — PDF テーブル、複数形式、OCR フォールバック
doc.ocr	シンプルな画像向けの Tesseract フォールバック
desktop.run_app_and_screenshot	Xvfb + xdotool + scrot + ウィンドウフォーカス
vision.click_anywhere	ネイティブのコンピューター操作ルーティング（Anthropic／OpenAI／Gemini のスキーマ）。Ollama／Deepseek では JSON プロンプトにフォールバック
vision.extract_visible_text / vision.fill_form_by_label	スクリーンショット → ビジョンモデル → 操作のループ
コード編集ループ
repo.fetch / repo.push	Vault からの SSH キー選択、known_hosts、終了時のキー破棄。エージェントが最初のターンで状況を把握できるよう、エンベロープで tree／readme／entrypoints／signals を返します
repo.map	トークン予算内で構造化シンボルマップを作成する Aider 方式
fs.read / fs.write / fs.patch / fs.list / fs.delete	クローン内のパス安全なファイル操作
cmd.run	クローンのパス内で任意のコマンドを実行
git.commit / git.diff / git.log	helmdeck-agent 名義でステージング、コミット、変更のレビュー
GitHub
github.create_issue / github.list_issues / github.list_prs / github.post_comment / github.create_release / github.search	Vault に保存された PAT。エージェントには決して表示されません
言語サイドカー
python.run	Python サイドカーイメージ内の CPython 3 + pytest + ruff + mypy
node.run	Node サイドカーイメージ内の Node 20 LTS + npm + pnpm + yarn + tsc
HTTP と認証情報
http.fetch	プレースホルダートークンを使った外部送信：URL／ヘッダー／本文内の ${vault:NAME} を置換

各パックの仕様については ADR 014–036 をご覧ください。また、新しい言語サイドカー（Rust、Go、Ruby など）の追加手順については docs/SIDECAR-LANGUAGES.md のランブックをご覧ください。独自パックの作成方法は CONTRIBUTING.md のコントリビューションガイドで説明しています。現在、特に役立つコントリビューションは SaaS API ラッパー（Slack、Linear、Stripe、Notion など）です。

ライセンス

Apache License, Version 2.0 の下でライセンスされています。同梱プロジェクトおよび依存プロジェクトの帰属表示については NOTICE を、コントリビューションガイドおよび SPDX ヘッダーの規則については CONTRIBUTING.md をご覧ください。

プルリクエストを送信すると、コントリビューションを同じ条件でライセンスすることに同意したものとみなされます（Apache 2.0 の Section 5 でコントリビューションの許諾について定めています。別途 CLA を提出する必要はありません）。

作者

Tosin Akinosho (@tosin2013)