カスタムアーティファクトソース (AGENTENGINE_IMAGE_SOURCE=custom)

仕組み

2つの独立したノブ（それぞれ任意）:

カスタムソースはホストすることのみを入れ替えます。イメージリポジトリ名とタグを付けることはビルドする時に固定されるため、ミラーは同じ名前、同じタグを付けること、そして独自のホストすることを使用して機械的にコピーできます。

5つの開発スタックイメージは、playground-ui、orchestration-engine、memory-server、runner-base、runner-base-typescript-langgraphです。

前提条件

• AGENTENGINE_IMAGE_SOURCE=custom 環境で

• source.yaml ~/.agentengine/source.yaml で（または $AGENTENGINE_IMAGE_SOURCE_FILE で設定されたパスで）

• 企業のCAはOSの信頼保存 (する)にある必要があります。--insecureフラグはありません（セキュリティを参照）。

ステップ 1 — イメージ名とタグを付ける

agentengine version --full を実行することで、現在の CLI をビルドするための正確なイメージ名とタグを付けるための情報を取得します。

agentengine version --full

出力例:

1.4.2 (commit: abc1234)runner-base: ghcr.io/mongodb/agent-engine-client-libraries/runner-base:v1.4.2runner-base-typescript-langgraph: ghcr.io/mongodb/agent-engine-client-libraries/runner-base-typescript-langgraph:v1.4.2playground-ui: ghcr.io/mongodb/agent-engine-client-libraries/playground-ui:v1.4.2orchestrator: ghcr.io/mongodb/agent-engine-client-libraries/orchestration-engine:v1.4.2memory-server: ghcr.io/mongodb/agent-engine-client-libraries/memory-server:v1.4.2

ミラーリングする際には、これらの正確な名前とタグを使用します。メジャーバージョン内のパッチリリースを通じても安定しています。変更されるのはバージョンサフィックスのみです。

ステップ 2: イメージのミラーリング (開発スタックをミラーリングする場合)

docker login ghcr.io                           # read access to MongoDB's GHCRdocker login artifactory.example.com           # write access to your registry
for img in playground-ui orchestration-engine memory-server runner-base runner-base-typescript-langgraph; do  docker pull ghcr.io/mongodb/agent-engine-client-libraries/$img:v1.4.2  docker tag  ghcr.io/mongodb/agent-engine-client-libraries/$img:v1.4.2 artifactory.example.com/acme-docker/$img:v1.4.2  docker push artifactory.example.com/acme-docker/$img:v1.4.2done

新しいCLIバージョンごとに繰り返します。リポジトリ名とタグの形式は安定しており、バージョン番号のみが変更されます。

ステップ 3 — CLI バイナリをホストする (バイナリのダウンロードをミラーリングする場合)

ネットワークでGitHubのリリースもブロックされている場合は、CLIバイナリをHTTPSサーバー（Artifactoryの汎用リポジトリが適しています）でホストし、静的マニフェスト形式に一致するmanifest.jsonを公開してください。

各OS/アーキテクチャの組み合わせに対応するバイナリファイルをアップロードし、それらを指すマニフェストを作成します。マニフェストのURLは、source.yamlではrelease.urlになります。

ステップ 4 — 書き込み (write) source.yaml

~/.agentengine/source.yaml、または$AGENTENGINE_IMAGE_SOURCE_FILEで設定したパスに配置します。

agentengine agent source setup      # interactive wizard: asks base/release/registry, validates before writingagentengine agent source template   # writes a commented, ready-to-edit starting point insteadagentengine agent source template --stdout   # print the template instead of writing it

base: publicrelease:  type: static  url: https://artifactory.example.com/acme-generic/agentic-cli/manifest.jsonregistry:  prefix: artifactory.example.com/acme-docker

base: publicregistry:  prefix: artifactory.example.com/acme-docker

base: publicrelease:  type: static  url: https://nexus.example.com/agentic-cli/manifest.json

base: publicrelease:  type: github  url: https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releasesregistry:  prefix: registry.example.internal/agentic

base: publicrelease:  type: static  url: https://artifactory.example.com/agentic-cli/manifest.jsonregistry:  prefix: artifactory.example.com/agent-engine-mirror

ステップ 5 — 検証

agentengine agent source validate $AGENTENGINE_IMAGE_SOURCE を事前に設定しなくてもファイルをチェックでき、成功するとアクティブ化するための正確な環境変数が表示されます。

agentengine agent source validate                          # standard discovery pathagentengine agent source validate ./some/other/source.yaml  # or an explicit path

AGENTENGINE_IMAGE_SOURCE=customAGENTENGINE_IMAGE_SOURCE_FILE=/Users/you/.agentengine/source.yaml

検証エラーが発生すると、ファイルがagentengine agent source setup、agentengine agent source template、または手動編集のいずれから取得されたかに関係なく、以下の「トラブルシューティング」に記載されているものと同じ固定メッセージが表示されます。

次に、それをアクティブ化し、解決されたルーティングを確認します。

export AGENTENGINE_IMAGE_SOURCE=customagentengine version --full

完全なミラーの場合、以下のように表示されます。

1.4.2 (commit: abc1234)source: custom  release:  https://artifactory.example.com/acme-generic/agentic-cli/manifest.json (static)  registry: artifactory.example.com/acme-dockerrunner-base: artifactory.example.com/acme-docker/runner-base:v1.4.2runner-base-typescript-langgraph: artifactory.example.com/acme-docker/runner-base-typescript-langgraph:v1.4.2playground-ui: artifactory.example.com/acme-docker/playground-ui:v1.4.2orchestrator: artifactory.example.com/acme-docker/orchestration-engine:v1.4.2memory-server: artifactory.example.com/acme-docker/memory-server:v1.4.2

出力内のイメージは、agentengine dev up によって docker pull に渡される正確な文字列です。

次に、agentengine self-update を実行してバイナリ更新パスをテストし、agentengine dev up を実行してイメージのプルが成功することを確認します。

静的リリース・マニフェストの形式

CLIはrelease.urlからこのファイルを取得し、セマンティックバージョニング（semver）が最も高いバージョンを選択して、現在のOSとアーキテクチャに一致するアセットを選択します。latestフィールドはありません。CLIはreleases配列から最大バージョンを計算するため、古いポインターが利用可能なアセットと不一致になることはありません。

{  "releases": [    {      "version": "1.4.2",      "assets": [        {          "os": "darwin",          "arch": "arm64",          "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_darwin_arm64",          "sha256": "9f2b...e1"        },        {          "os": "linux",          "arch": "amd64",          "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_linux_amd64",          "sha256": "4c7a...bd"        }      ]    }  ]}

CLIは、解析時にsha256が64文字の16進数stringであることを検証し、インストール前にダウンロードされたバイナリを再検証します。

セキュリティ

HTTPSが必須であり、``--insecure``によるオーバーライドはできません。SHA-256はバイナリがマニフェストと一致していることを検証しますが、マニフェスト自体を暗号的に署名するものではありません。プレーンなHTTP経由では、攻撃者がダウンロードURLとハッシュされた値の両方を書き換えることができ、検証が通過してしまいます。TLSは、マニフェストの整合性を保証する唯一の手段です。オンプレミスのリリースサーバーはTLSを使用する必要があります。

企業CAエアギャップ環境のエンタープライズでは、通常、内部認証局を運用しています。CLIはGoのTLSスタックを使用しており、OSの証明書信頼保存 (する)に従います。内部HTTPSホストするでAGENTENGINE_IMAGE_SOURCE=customを使用する前に、企業CAをOSの信頼保存 (する)にインストールする必要があります。--insecureまたは--cacertフラグはありません。内部ホストに対するTLS検証の失敗は、CLIのバグではなく、信頼ストアの問題です。

生成された local-dev イメージ内のパッケージインストールは、個別の信頼ストアです。ローカル agentengine dev up での企業 TLS インスペクションを参照してください。

レジストリ認証。CLIはDockerの認証情報を保存またはマネージドしません。レジストリに認証が必要な場合は、agentengine dev upを実行する前にdocker login <registry>を1回実行してください。CLIはイメージ参照をDockerに渡します。Dockerは独自のアンビエント認証情報保存 (する)を使用します。

``source.yaml`` の検出。CLIは、source.yamlを$AGENTENGINE_IMAGE_SOURCE_FILE（設定されている場合）または~/.agentengine/source.yamlからのみ読み込みます。現在の作業ディレクトリから自動的に読み込まれることはありません。読み込まれると、クローンされたリポジトリが自己更新を攻撃者が制御するホストするにリダイレクトする可能性があるためです。

トラブルシューティング