사용자 지정 아티팩트 소스 (`AGENTENGINE_IMAGE_SOURCE=custom`)

custom 소스는 MongoDB의 GitHub Releases 및 GHCR 대신 사용자의 호스팅된 인프라스트를 통해 CLI 바이너리 다운로드 및 개발 스택 이미지 풀을 전송합니다. 이 서비스는 ghcr.io 또는 github.com에 접근할 수 없는 경우의 경리된 네트워크 환경(에어 갥프, 유출 제한)을 위해 설계되었습니다.

작동 방식

각각 선택 사항인 두 개의 독립적인 노브:

차단	제어	영향을 받는 명령어
`release`	CLI 바이너리 다운로드 호스팅	`agentengine self-update`, 일일 업데이트 알림
`registry`	개발 이미지 호스팅(5 개 이미지)	`agentengine dev up`

사용자 지정 소스는 호스팅하다만 교체합니다. 이미지 리포지토리 이름과 태그를 지정하다는 빌드 시점에 고정되므로 미러는 동일한 이름, 동일한 태그를 지정하다, 사용자의 호스팅하다를 사용하여 기계적으로 복사할 수 있습니다.

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 플래그는 없습니다(보안) 참조).

참고

재정의 변수 이름은 고정되어 있습니다. CLI는 AGENTENGINE_IMAGE_SOURCE 및 AGENTENGINE_IMAGE_SOURCE_FILE을(를) 읽습니다. 더 이상 사용되지 않는 AP_SOURCE / AP_SOURCE_FILE 이름은 읽지 않으며, 둘 중 하나를 설정하면 명령이 실패합니다.

플랫폼 연결이 필요하지 않습니다. CLI가 로컬에서 소스를 확인하므로 에어갭 또는 송신 제한 머신은 AGENTENGINE_IMAGE_SOURCE=custom 만으로 구성됩니다. public-artifacts를 참조하세요.

1단계 1 — 이미지 이름 및 태그를 지정하다

현재 CLI 빌드에 대한 정확한 이미지 이름과 태그를 가져오려면 agentengine version --full을(를) 실행하세요.

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 릴리스도 차단하는 경우, HTTPS 서버(Artifactory 일반 리포지토리가 적합함)에 CLI 바이너리를 호스팅하고 정적 매니페스트 형식과 일치하는 manifest.json을(를) 게시하세요.

각 OS/아키텍처 조합에 대한 바이너리 파일을 업로드한 다음, 해당 파일을 가리키는 매니페스트를 생성합니다. 매니페스트 URL은 source.yaml에서 release.url이(가) 됩니다.

4 단계 — 쓰기 (write) `source.yaml`

~/.agentengine/source.yaml 또는 $AGENTENGINE_IMAGE_SOURCE_FILE에 설정한 경로에 배치합니다.

권장 사항: CLI를 사용하여 생성

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

둘 다 표준 검색 경로(또는 기존 파일의 덮어쓰기 프롬프트를 건너뛰려면 --force)에 쓰기 (write)하고 쓰기 (write) 전에 자체 검증을 수행하므로 결과가 로드될 것이 보장됩니다. YAML을 직접 편집하는 것보다 프롬프트에 응답하는 것이 더 쉬울 때는 agentengine agent source setup을 사용하고, 파일을 직접 편집하려는 경우에는 agentengine agent source template를 사용하세요. 아래 예시에서 무엇을 채워야 하는지 확인할 수 있습니다.

전체 미러 — 호스팅하는 시스템의 바이너리 및 이미지

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

이미지만 해당 — 바이너리는 Github에 유지

네트워크에서 github.com은 허용하지만 ghcr.io은 차단하는 경우 사용합니다.

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

바이너리 전용 — 이미지는 GHCR에 유지

네트워크에서 ghcr.io은 허용되지만 Github 릴리스 다운로드는 차단되는 경우 사용합니다.

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

GitHub 형태의 릴리스 API — 온프레미스 Github 엔터프라이즈

인프라가 GitHub의 JSON 형태(예: GitHub 엔터프라이즈)로 릴리스 API를 노출하는 경우 정적 매니페스트를 호스팅하는 대신 사용합니다.

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

base: public 현재 public이(가) 확인되는 모든 항목을 상속합니다. 이는 재정의하지 않는 블록에만 적용됩니다. 고정된 registry.prefix 또는 release.url는 사용자의 것입니다. 블록을 고정하여 확실하게 하세요. public-artifacts.md를 참조하세요.

`source.yaml` 필드 참조

필드	필수 사항	설명
`base`	No (default: `public`)	재정의되지 않은 모든 항목에 대한 대체 소스: `public`
`release.type`	`release`이(가) 있는 경우 예	`static` — 정적 JSON 매니페스트(이 문서); `github` — GitHub 형태의 릴리스 API
`release.url`	`release`이(가) 있는 경우 예	매니페스트(정적) 또는 API 베이스(Github)의 전체 HTTPS URL입니다. 사용해야 함 `https://`
`registry.prefix`	`registry`이(가) 있는 경우 예	레지스트리 호스트 + 경로, 스키마 없음, 태그 없음 (예: `artifactory.example.com/acme-docker`)

release 또는 registry 중 하나 이상이 필요합니다. 둘 다 없는 source.yaml는 기본 소스와 동일하며 거부됩니다.

$AGENTENGINE_IMAGE_SOURCE_FILE ~/.agentengine/source.yaml 검색 경로를 재정의합니다. 설정된 경우, 파일이 없거나 읽을 수 없으면 홈 파일로 조용히 대체되는 대신 하드 오류가 발생합니다.

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"        }      ]    }  ]}

필드	유형	설명
`releases`	배열	버전당 하나의 항목입니다. CLI는 가장 높은 semver를 선택합니다.
`releases[].version`	문자열	의미론적 버전(예: `1.4.2`)
`releases[].assets`	배열	OS/아키텍처 조합당 하나의 항목
`assets[].os`	문자열	`darwin`, `linux` 또는 `windows`
`assets[].arch`	문자열	`amd64` or `arm64`
`assets[].url`	문자열	바이너리에 대한 전체 HTTPS URL
`assets[].sha256`	문자열	바이너리의 64자 16진수 SHA-256 다이제스트

CLI는 구문 분석 시 sha256이(가) 64자 16진수 string인지 확인하고 설치 전에 다운로드한 바이너리를 다시 확인합니다.

보안

HTTPS가 필요하며 ``--insecure`` 재정의는 사용할 수 없습니다. SHA-256은 바이너리가 매니페스트와 일치하는지 확인하지만, 매니페스트 자체에 대한 암호화 서명은 없습니다. 일반 HTTP를 통해 공격자가 다운로드 URL과 해시를 모두 다시 작성할 수 있으며, 이 경우에도 확인은 통과됩니다. TLS는 유일한 매니페스트 무결성 보장입니다. 온프레미스 릴리스 서버는 TLS를 사용해야 합니다.

기업 CA. 에어갭 엔터프라이즈는 일반적으로 내부 인증 기관을 실행합니다. CLI는 OS 인증서 신뢰 저장소를 따르는 Go의 TLS 스택을 사용합니다. 내부 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>을(를) 한 번 실행하세요. CLI는 이미지 참조를 Docker에 전달하며, Docker는 자체적인 주변 자격 증명 저장소를 사용합니다.

``source.yaml`` 검색. CLI는 source.yaml이(가) 설정된 경우 $AGENTENGINE_IMAGE_SOURCE_FILE 에서만, 또는 ~/.agentengine/source.yaml에서 을(를) 로드합니다. 현재 작업 디렉토리에서는 절대 자동으로 로드되지 않습니다. 그렇게 하면 복제된 리포지토리가 자체 업데이트를 공격자가 제어하는 호스팅하다로 리디렉션할 수 있기 때문입니다.

문제 해결

오류	원인	수정
`AGENTENGINE_IMAGE_SOURCE=custom but no source.yaml found`	검색된 두 경로 모두에 파일이 없습니다.	`~/.agentengine/source.yaml`을(를) 생성하거나 `$AGENTENGINE_IMAGE_SOURCE_FILE`을(를) 설정하세요.
`$AGENTENGINE_IMAGE_SOURCE_FILE points to "..." which does not exist`	`$AGENTENGINE_IMAGE_SOURCE_FILE` 설정되었으나 파일이 누락됨	경로를 확인하세요. 환경 변수가 설정되어 있을 때 파일이 존재해야 합니다.
`source.yaml: release.url must be an https:// URL`	URL 시작 문자 `http://`	`https://`을(를) 사용하세요. 서버에 TLS를 추가합니다.
`source.yaml: registry.prefix "..." must not include a scheme`	접두사가 있습니다. `https://`	스키마를 제거하고 bare를 사용하세요 `host/path`
`source.yaml: registry.prefix "..." must not contain a tag or digest`	접두사에는 `:v1` 접미사가 포함됩니다	호스팅하다 + 경로만 사용하세요 (마지막 `/` 뒤에 콜론을 사용하지 마세요)
`source.yaml: custom source needs at least one of 'release' or 'registry'`	두 블록 모두 없음	최소 하나의 블록 추가
`release manifest: HTTP 404 fetching ...`	잘못된 URL이거나 파일이 아직 업로드되지 않았습니다.	`release.url`을(를) 확인하고 파일에 액세스할 수 있는지 확인하세요.
`release manifest: no asset for darwin/arm64 in version 1.4.2`	OS/arch 항목이 누락되었습니다	매니페스트에 누락된 자산 항목 추가
`release manifest: asset sha256 "xyz" is not a 64-char hex digest`	다이제스트가 너무 짧거나 16진수가 아닙니다	바이너리의 `sha256sum`을(를) 계산하고 전체 64자 16진수를 붙여넣으세요.
내부 호스팅 서버에서 TLS 확인 실패	OS 신뢰 저장소에 없는 기업 CA	CA를 설치하세요. `--insecure` 플래그가 없습니다.
이미지 풀이 실패했습니다. (에서) `agentengine dev up`	이미지가 미러링되지 않았거나 `docker login`이(가) 누락되었습니다.	이미지를 반사하세요; `docker login <registry>`을 먼저 실행.

돌아가기

corporate-tls

환경 변수

사용자 지정 아티팩트 소스 (AGENTENGINE_IMAGE_SOURCE=custom)