heliograph

---

誰かはそのマシンにアクセスできます。あなたはできませんが、何を尋ねればよいかを知っているのはあなたです。heliograph は、その間を単なる中継ではなくループとしてつなぎます。あなたがステップを公開すると、それが向こう側で実行され、一連の実行全体がログとして戻ってきます。成功した場合も失敗した場合も、すべての行に UTC のタイムスタンプが付与されます。

you        heliograph send net-probe ────────────────▶ transport
station    picks it up within seconds, runs it
           pushes status, then the log ──────────────▶ transport
you        heliograph logs --last --gaps ◀────────────

つなぐ3つの方法

heliograph は、ログインできないマシンにリクエストを届け、ログを持ち帰ります。その間をつなぐ方法は3つあり、違いはひとつだけです。何が、どれくらいの間保持されるかです。

Beacon。 あなたはマシンにアクセスできず、マシンもあなたにアクセスできません。ただし、双方がアクセスできる合意済みの場所があります。そこにリクエストを置いて、その場を離れます。後でマシンがその場所に立ち寄り、リクエストを受け取って実行し、あなたが回収できるようログを残します。誰も接続されることはありません。途中に待つのは メッセージ です。実行するコードはすでに向こう側にあり、実行前に読み取れるため、3つの中で最も安全です。一方、次にマシンが立ち寄るまで待つ必要があるため、最も時間がかかります。

Flare。 マシンの入口に直接アクセスできます。ノックしてリクエストを渡し、実行中は入口で待ち、同じ訪問の間にログを受け取って持ち帰ります。途中に待機するものはなく、接続も開いたままになりません。受け取りを待つ必要がないため、より高速です。その代わり、コードを持ち込むのはあなたです。マシンはコードを事前に審査するのではなく、入口 を信頼します。

Beam。 あなたとマシンが接続を確立し、開いたままにします。どちら側も好きなときに発信でき、接続を切るまで相手はすぐにそれを受信できます。メッセージでもノックでもない、実際のセッションです。接続が開いている間は何でもその回線を通る可能性があるため、最も危険にさらされます。意図的に有効化し、作業が終わったら閉じます。設計中であり、まだ選択できるトランスポートではありません。

ひと言でまとめると、beacon は メッセージ を保持し、flare は 一度のやり取り を行い、beam は 接続そのもの を保持します。

こんな状況に心当たりはありませんか

• 本番環境への SSH アクセスがなく、今後も付与される予定がありません。
• 環境がエアギャップ化されているか、あなたが参加していない踏み台サーバー、ジャンプホスト、VPN の背後にあります。
• クライアント所有または顧客管理の環境です。ログインできるのは相手側のスタッフだけです。
• アクセスを妨げているのは能力ではなくポリシーです。制限、変更管理、他者の承認が必要といった事情があります。
• **「これを実行して出力を貼り付けてもらえますか」**のやり取りが4回目に入り、返ってきたのは端末の半分だけを写したスクリーンショットでした。
• 調査を進めているAI コーディングエージェントとして、誰かの要約ではなく証拠が必要です。

SSH で直接ログインできるなら、これは必要ありません。

3 つの役割、1 つの境界

境界とは隔たりであり、その構成で一度だけ明示します。

制御	お使いのマシン：heliograph CLI、heliograph mcp、それらを操作するスキルです。Go を使い、手前側で利用できるものは何でも使います
トランスポート	チャネル：git、リレー、ファイル共有、バンドル、オブジェクトストアです。すべて 1 つのインターフェースの背後にあり、読み取り専用のゲートを 1 か所に集約することで、トランスポートごとに挙動がずれるのを防ぎます
ステーション	向こう側：プライベートなトランスポートリポジトリに配置する station/bash/ です。Bash 4 以上、git、GNU coreutils が必要です。パッケージも、認証情報も、トンネルもありません

向こう側にインストールされるものは一切ありません。 ステーションは、実行前に中身を読めるプレーンテキストです。bash が使える環境では Bash 4 以上、bash がなく、今後も導入されない Windows 環境では PowerShell 5.1 を使います。さらに、CLI がペイロードを運ぶための 1 つのファイルを除き、station/ に Go が含まれることはありません。CI でこれを徹底しています。何かをインストールすること自体が独立した変更要求となる、ロックダウンされたマシンでは、この制約こそが本提案の核心です。

インストール

# Linux and macOS, from a release
curl -sSL https://github.com/heliograph-io/heliograph/releases/latest/download/heliograph-linux-amd64 \
  -o /usr/local/bin/heliograph && chmod +x /usr/local/bin/heliograph

# or from source
go install github.com/heliograph-io/heliograph/cmd/heliograph@latest

単一の静的バイナリで、ランタイムは不要です。各リリースにはチェックサムが公開され、バイナリにはビルド時のステーションペイロードが含まれています。

ビルドは再現可能です。packaging/reproduce.sh v0.4.3 を実行すると、タグからリリース済みのすべての成果物を再ビルドし、公開済みのハッシュが得られます。つまり、「パス上のバイナリは、読んだソースそのもの」ということを、私たちの主張としてではなく、自分で確かめられます。まだ対象外の内容も含む詳細については、docs.heliograph.io/provenance をご覧ください。

エージェントスキル — Claude Code、Codex、Cursor などから同じループを実行します。

/plugin marketplace add dbhq-uk/marketplace
/plugin install heliograph@dbhq         # Claude Code
./install-codex.sh                      # Codex, from a clone
./install.sh                            # Claude Code, from a clone
npx skills add heliograph-io/heliograph       # any agent, via skills.sh

使い方

heliograph bootstrap ~/transport/payments             # plant the station payload
heliograph init payments --dir ~/transport/payments   # git, the default
heliograph plant                                      # what to send the operator
heliograph send net-probe HOSTS="sql01 sql02"         # publish a request
heliograph watch                                      # follow it
heliograph logs --last                                # read the whole log
heliograph logs --last --gaps                         # where it stalled
heliograph doctor                                     # will this work from here
heliograph mcp                                        # serve all of the above as tools

オペレーターの作業は、plant の出力どおりに進めるだけです。トランスポートリポジトリをクローンし、./start.sh を実行したら、あとはその場を離れます。このループはオペレーターが許可しない限り読み取り専用です。各ステップは自らを宣言し（# heliograph-mode: read-only または action）、どちらも宣言しないステップは実行されません。また、--allow-actions を付けて起動しない限り、ステーションはアクションを拒否します。root として実行することもありません。

エージェントには、heliograph mcp が MCP ツールとして入力するのと同じ CLI を提供します。

claude mcp add heliograph -- heliograph mcp

ゲートの位置は変わりません。ツール呼び出しはリクエストを公開しますが、それを実行するかどうかは引き続きステーションが判断します。

覚えておく価値があるのは --gaps です。「内容を読む前に、タイムスタンプ列の間隔をスキャンする」という指示は、この手法で最も価値のあるものであり、計算によって実現します。

$ heliograph logs --last --gaps
demo-20260906T183628Z.txt
5 captured lines

1 interval(s) of 10s or more, longest first.
Each is attributed to the line BEFORE it, which is what was running.

   3m12s  after  09:14:02 | Refreshing state...

間隔は、その直前の行に属します。行のタイムスタンプは、その行が生成された時刻を示すため、長い間隔があれば、時間がかかったのは直前の行に記された操作です。すべての行に同じタイムスタンプが付いたログは、「間隔なし」ではなくエラーとして報告されます。

ステータス

git 経由の制御 CLI	動作します。標準のステーションを使ったエンドツーエンドテスト済みです
heliograph bootstrap	動作します。バイナリが、それと一緒にビルドされたステーションを配置します
--gaps	動作します
MCP サーバー（heliograph mcp）	動作します
bash ステーション	git 経由で使用中です。ループ、ゲート、キャプチャ、Azure ホスト、Kubernetes、Windows ランチャーに対応しています
relay	エンドツーエンドで動作します。heliograph init --transport relay で選択でき、両方のステーションが実装し、relay サーバーがデプロイ済みです。また、CI では TestCLIDrivesARelayStation がループ全体を実行します
ファイル共有、バンドル、オブジェクトストア	bash ステーションには3種類すべてのステーショントランスポートがあります（station/bash/transports/）。init で share、bundle、objstore を選択できます。PowerShell ステーションには share がありますが、bundle と objstore はありません
Azure Blob	エンドツーエンドで動作します。CLI ではなく、ステーションのペイロード内の drop.sh を介して動作し、Azure Function ホストで使用されています
PowerShell ステーション	提供済みです。station/powershell/ は約2,600行で、git、share、relay に対応しており、CI では Windows ランナー上で実行します。設計についてはA8を参照してください
ドキュメントサイト	docs.heliograph.io：CLI、トランスポート、そしてその先にあるステーション、ランナー、ステップ、ホスト、Azure、Windows、コンテナー、サービス、シークレット、セキュリティ、キャプチャの契約について説明しています

ギャップの片側だけで動くものはトランスポートとは言えないため、この表では両側を示しています。git と relay は CLI からエンドツーエンドで実行でき、CI で検証済みです。ほかに必要なものと、その順序についてはロードマップを参照してください。

この表はしばらく誤っていました。その理由は記録に残す価値があります。 2026年9月21日まで、relay は「半分のトランスポート」であり、「選択できる CLI コマンドはない」と記載されていました。また、ステーションには share、bundle、オブジェクトストア用のトランスポートがなく、PowerShell ステーションは「計画中」とされていました。このリポジトリのコードに照らすと、4つとも誤りでした。ドキュメントサイトに食い違いがなかったのは、transports_doc_test.go が initTransports とステーションのトランスポートディレクトリに結び付けられていたためです。一方、このファイルには何も結び付けられていませんでした。現在は TestReadmeTransportClaimsMatchTheCode によって検証されています。

その影響はここだけにとどまりませんでした。この README がドキュメントサイトと矛盾していたため、skills.dbhq.uk/heliograph は意図的に、より控えめな説明を公開し、「heliograph がどちらが正しいかを確定するまで」控えめな表現を保つと記録していました。今回、それが確定しました。

relay

両側から通常の HTTPS 経由で接続するため、環境に git ホスト、ストレージアカウント、VNet は必要ありません。ホスト型で利用でき、同じバイナリでセルフホストもできます。

エンドツーエンドではまだ利用できません。 ステーション側は完成しており、サーバーもデプロイ済みです。ただし、これを選択できる CLI コマンドがないため、近い側が未完成です。

relay はログを読み取ることも、ステーションに何かを実行させることもできません。 重要なのは後者です。リクエストを偽造できる relay があれば、すべての環境で同時にコードが実行されてしまいます。コンテンツは、relay が決して保持しない鍵でエンドツーエンド暗号化され、すべてのメッセージに署名が付与されます。独自仕様の仕組みはなく、age のプリミティブと Ed25519 を使っています。DBHQ が何を正直に主張でき、何を主張できないかも含めた詳細は、docs/specs/2026-09-06-relay-encryption-design.mdを参照してください。relay サーバーは独立したリポジトリであるheliograph-io/heliograph-relayにあります。サーバーは鍵を保持せず、転送するものを一切読み取れないことが、誰の目にも明らかでなければならないためです。

ビームとは何か、そしてその代償

ビームは設計済みですが、まだ実装されていません。以下は、実装されたときの動作です。

3つの形態のうち2つは、接続を開いたままにしません。ビーコンは両側からアクセスできる場所にメッセージを残します。常に到達可能である必要はなく、インバウンドポートも、エンドポイントも、トンネルも不要です。フレアは呼びかけて応答を待ち、立ち去ります。応答が返ってきたあとも回線を開いたままにすることはありません。この2つを使えば、回線を開いたままにできない環境でも、タスク全体を完了できます。

ビームは双方向の回線をライブで開いたままにします。つまり、トンネルです。ブルーチームは、回線を開いたままにするチャネルをトンネルとみなします。実際にトンネルだからです。そのため、両端で明示的に有効化しない限りオフであり、封印され署名されていて、許可するように起動されていない限り、ステーションはトンネルを確立しません。逆方向の接続が禁止されている環境では、ビーコンとフレアで対応でき、失われるのは遅延だけです。

すべてのコマンドは引き続き遠隔側で実行されます。正当なアクセス権を持つ人が、実行を許可したからです。

レイアウト

cmd/heliograph/         the control CLI, and `heliograph mcp`
cmd/heliograph-seal/    key generation for the relay transport
cmd/heliograph-site/    the static site generator
internal/transport/     git | relay | share | bundle | objstore
internal/bootstrap/     `heliograph bootstrap`: plants the embedded station
internal/wire/          the request and status documents that cross the gap
internal/seal/          sign-then-encrypt, for the relay
internal/logfile/       gap analysis
internal/mcp/           JSON-RPC over stdio, no dependencies
internal/estate/        which transport a name refers to
internal/plant/         what to send the operator
station/bash/           the bash station: everything that runs on the far side
station/bootstrap.sh    the no-CLI bootstrap: clone this repo, run it by hand
skills/heliograph/      the agent skill: drives the CLI, and nothing else
tests/                  the station's own suite, conformance contract included
site/content/           the documentation, one source, three renderings
infra/                  terraform: DNS, Pages, R2 state
docs/specs/             the designs, written before the code

以前は、2つの部分が別々のリポジトリに分かれていました。分割の基準は接続の両側ではなく、Go と bash の違いでした。そのため、読者はどちらの部分を見ているのかを自分で判断する必要がありました。dbhq-uk/heliograph-skill は、完全な履歴とともに 2026-09-08 に統合されました。その経緯は docs/specs/2026-09-08-station-and-skill-merge.md に記載されています。

そのリポジトリは 2026-09-17 に削除され、名前は現在使われていません。統合後も公開状態でアーカイブされていました。アーカイブされたリポジトリは到達不能ではなく読み取り専用です。引き続きクローンでき、install.sh も実行できました。また、その中のステーションにはリクエスト環境変数のガードがまったくありませんでした（heliograph-cloud#274）。履歴は非公開で保管されており、このリポジトリ自体の履歴に統合の記録が残っています。

開発

ROADMAP.md には、heliograph の目的、現在動作する機能、現在・次・将来のエピックなど、作業の進捗が記載されています。既知の不具合には type: bug のラベルが付いています。 CONTRIBUTING.md では開発への参加方法を説明し、 AGENTS.md は開発を行う AI エージェント向けです。スキルは skills/heliograph/SKILL.md にあります。 docs/dev-setup.md では、ソースからセットアップしてライブ編集する方法を説明しています。

ライセンス

Apache 2.0（著作権 © 2026 DBHQ Consulting Ltd）。site/content/ 内の文章は CC BY 4.0 です。2026-09-17 に MIT から再ライセンスされました。b689f9c までのすべてのコミットは、これまでどおり MIT の下で永久に利用できます。Apache を MIT ではなく採用した理由と、この変更によって失われない権利については、NOTICE を参照してください。

リレーは別のリポジトリで、ライセンスも別です。 heliograph-relay は FSL-1.1-ALv2 のフェアソースで、各リリースから2年後に Apache 2.0 へ移行します。どの形態も利用制限されません。ビーコン、フレア、ビームはすべて、自分でホストするリレーで動作します。

プロフェッショナルサービスの許諾と、その制約についての率直な説明を含む全文： https://docs.heliograph.io/licence