Fuente de artefacto personalizada (`AGENTENGINE_IMAGE_SOURCE=custom`)

La fuente custom dirige descargar binarias de CLI y las extracciones de imágenes de pila de desarrollo a través de su propia infraestructura host en lugar de las versiones de Github de MongoDB y GHCR. Está diseñado para entornos de red aislados (sin conexión a Internet, con salida restringida) donde ghcr.io o github.com no son accesibles.

Cómo funciona

Dos perillas independientes, cada una opcional:

Bloque	Controles	Comandos afectados
`release`	Host para descargar binarios de CLI	`agentengine self-update`, aviso de actualizar diario
`registry`	Host de imágenes de desarrollo (5 imágenes)	`agentengine dev up`

La fuente personalizada solo intercambia el host — los nombres de repositorio de imágenes y las etiquetas permanecen integrados en el momento de compilar, por lo que su réplica puede copiar mecánicamente: los mismos nombres, las mismas etiquetas, su host.

Las cinco imágenes de la pila de desarrollo son: playground-ui, orchestration-engine, memory-server, runner-base, runner-base-typescript-langgraph.

Requisitos previos

AGENTENGINE_IMAGE_SOURCE=custom en el entorno
source.yaml en ~/.agentengine/source.yaml (o en una ruta establecida en $AGENTENGINE_IMAGE_SOURCE_FILE)
Su CA corporativa debe estar en el almacenar de confianza del sistema operativo — no hay ninguna marca --insecure (consulte Seguridad)

Nota

Los nombres de las variables de anulación son fijos. La CLI lee AGENTENGINE_IMAGE_SOURCE y AGENTENGINE_IMAGE_SOURCE_FILE. Los nombres retirados AP_SOURCE / AP_SOURCE_FILE ya no se leen, y configurar cualquiera de ellos hace que el comando falle.

No se necesita conectividad de plataforma. La CLI resuelve la fuente localmente, por lo que una máquina aislada o con restricciones de salida se configura solo con AGENTENGINE_IMAGE_SOURCE=custom. Consulte public-artifacts.

Paso 1 — Obtener nombres y etiquetas de imagen

Ejecute agentengine version --full para obtener los nombres exactos de las imágenes y la etiqueta para compilar actual de la CLI:

agentengine version --full

Ejemplo de salida:

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

Utilice estos nombres y etiquetas exactos al reflejar. Se mantienen estables en las versiones de parche dentro de una versión principal; solo cambia el sufijo de la versión.

Paso 2 — Imágenes espejo (si se duplica la pila de desarrollo)

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

Repita para cada nueva versión de CLI. Los nombres de los repositorios y el formato de las etiquetas son estables; solo cambia el número de versión.

Paso 3 — Host el binario de la CLI (si se reflejan las descargas de binarios)

Si su red también bloquea las versiones de GitHub, aloje los binarios de la CLI en un servidor HTTPS (un repositorio genérico de Artifactory funciona bien) y publique un manifest.json que coincida con el formato de manifiesto estático.

Suba los archivos binarios para cada combinación de SO/arquitectura, luego cree el manifiesto que apunte a ellos. La URL del manifiesto se convierte en release.url en source.yaml.

Paso 4 — guardar `source.yaml`

Coloque en ~/.agentengine/source.yaml, o en la ruta que configuró en $AGENTENGINE_IMAGE_SOURCE_FILE.

Recomendado: generarlo con la 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

Ambos guardan en la ruta de detección estándar (o --force para omitir la solicitud de sobrescritura en un archivo existente) y se autovalidan antes de guardar, por lo que se garantiza que el resultado se cargará. Utilice agentengine agent source setup cuando responder a las indicaciones sea más fácil que editar YAML manualmente; utilice agentengine agent source template cuando prefiera editar el archivo usted mismo — los ejemplos siguientes muestran qué rellenar.

Espejo completo — binario e imágenes de su host

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

Solo imágenes — el binario permanece en GitHub

Usar cuando su red permite github.com pero bloquea ghcr.io:

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

Solo binario — las imágenes permanecen en GHCR

Utilice cuando su red permite ghcr.io pero bloquea descargar versiones de Github:

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

API de versiones al estilo de Github — Github empresas en las instalaciones

Utilizar cuando su infraestructura exponga una API de versiones con el formato JSON de Github (por ejemplo, Github empresa) en lugar de alojar un manifiesto estático:

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

Reflejando el lanzamiento público

Para implementaciones que reflejan los artefactos de la versión pública:

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

base: public hereda lo que public resuelva actualmente. Eso solo se aplica a bloques que no anule: un registry.prefix o release.url anclado es suyo. Fije el bloque para asegurarse de ello. Ver public-artifacts.md.

`source.yaml` referencia de campo

Campo	Requerido	Descripción
`base`	No (default: `public`)	Fuente de respaldo para todo lo que no se haya anulado: `public`
`release.type`	Sí, si `release` está presente	`static` — manifiesto JSON estático (este documento); `github` — API de versiones con formato GitHub
`release.url`	Sí, si `release` está presente	URL HTTPS completa del manifiesto (estático) o la base de la API (Github). Debe usar `https://`
`registry.prefix`	Sí, si `registry` está presente	Host del registro + ruta, sin esquema, sin etiqueta (p. ej., `artifactory.example.com/acme-docker`)

Se requiere al menos uno de release o registry — un source.yaml sin ninguno de ellos es equivalente a la fuente base y se rechaza.

$AGENTENGINE_IMAGE_SOURCE_FILE sobrescribe la ruta de descubrimiento de ~/.agentengine/source.yaml. Cuando se configura, un archivo que falta o que no se puede leer es un error grave en lugar de una solución alternativa silenciosa al archivo principal.

Paso 5 - Verificar

agentengine agent source validate comprueba el archivo sin requerir que $AGENTENGINE_IMAGE_SOURCE se configure primero, y en caso de éxito imprime las variables de entorno exactas para activarlo:

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

Los fallos de validación muestran los mismos mensajes anclados que se enumeran en la sección Solución de problemas a continuación, independientemente de si el archivo procedía de agentengine agent source setup, agentengine agent source template o de una edición manual.

Luego actívelo y confirme el enrutamiento resuelto:

export AGENTENGINE_IMAGE_SOURCE=customagentengine version --full

Para un espejo completo debería ver:

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

Las imágenes en la salida son las cadenas exactas pasadas a docker pull por agentengine dev up.

A continuación, ejecute agentengine self-update para probar la ruta de actualizar binaria, y agentengine dev up para confirmar que las extracciones de imágenes se completan con éxito.

Formato de manifiesto de lanzamiento estático

La CLI obtiene este archivo de release.url, selecciona la versión semver más alta y elige el activo que coincide con el sistema operativo y la arquitectura actuales. No hay campo latest — la CLI calcula la versión máxima del arreglo releases, por lo que un puntero obsoleto nunca puede estar en desacuerdo con los activos disponibles.

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

Campo	Tipo	Descripción
`releases`	arreglo	Una entrada por versión. CLI elige el semver más alto.
`releases[].version`	string	Versión semántica (p. ej. `1.4.2`)
`releases[].assets`	arreglo	Una entrada por combinación de SO/arquitectura
`assets[].os`	string	`darwin`, `linux`, o `windows`
`assets[].arch`	string	`amd64` or `arm64`
`assets[].url`	string	URL HTTPS completa para el binario
`assets[].sha256`	string	Resumen SHA-256 hexadecimal de 64caracteres del binario

La CLI valida que sha256 es un string hexadecimal de 64caracteres en tiempo de análisis y vuelve a verificar el binario descargado antes de la instalación.

Seguridad

HTTPS es obligatorio, sin anulación de ``--insecure``. SHA-256 verifica que el binario coincide con el manifiesto, pero nada firma criptográficamente el propio manifiesto. A través de HTTP sin cifrar, un atacante puede reescribir tanto la URL para descargar como la encriptada juntas, y la verificación sigue siendo exitosa. TLS es la única garantía de integridad del manifiesto. Los servidores de lanzamiento on-premises deben usar TLS.

CA corporativa. Las empresas con aislamiento de red suelen ejecutar una autoridad de certificación interna. La CLI utiliza la pila TLS de Go, que sigue el almacenar de confianza de certificados del sistema operativo. Su CA corporativa debe instalarse en el almacén de confianza del sistema operativo antes de usar AGENTENGINE_IMAGE_SOURCE=custom con un host HTTPS interno. No hay indicador --insecure o --cacert. Un fallo de verificación de TLS contra un host interno es un problema de almacén de confianza, no un error de CLI.

Las instalaciones de paquetes dentro de la imagen local-dev generada son un almacenar de confianza independiente. Consulte Inspección TLS corporativa en agentengine dev up local.

Autenticación de registro. La CLI nunca almacena ni gestiona credenciales de Docker. Si su registro requiere autenticación, ejecute docker login <registry> una vez antes de ejecutar agentengine dev up. La CLI pasa referencias de imágenes a Docker, que utiliza su propio almacenar de credenciales ambientales.

Detección de ``source.yaml``. La CLI carga source.yaml solo desde $AGENTENGINE_IMAGE_SOURCE_FILE (cuando está configurado) o ~/.agentengine/source.yaml. Nunca se autocarga desde el directorio de trabajo actual; hacerlo permitiría que un repositorio clonado redirigiera la operación de actualizar automáticamente a un host controlado por un atacante.

Solución de problemas

Error	Causa	Corregir
`AGENTENGINE_IMAGE_SOURCE=custom but no source.yaml found`	Ningún archivo en ninguna de las rutas buscadas	Crear `~/.agentengine/source.yaml` o establecer `$AGENTENGINE_IMAGE_SOURCE_FILE`
`$AGENTENGINE_IMAGE_SOURCE_FILE points to "..." which does not exist`	`$AGENTENGINE_IMAGE_SOURCE_FILE` establecido pero falta el archivo	Compruebe la ruta; el archivo debe existir cuando se establece la variable de entorno.
`source.yaml: release.url must be an https:// URL`	La URL comienza con `http://`	Utilice `https://`; añada TLS a su servidor
`source.yaml: registry.prefix "..." must not include a scheme`	Prefijo tiene `https://`	Remover el esquema; usar tal cual `host/path`
`source.yaml: registry.prefix "..." must not contain a tag or digest`	El prefijo incluye el sufijo `:v1`	Utilice solo host + ruta (sin dos puntos después del último `/`)
`source.yaml: custom source needs at least one of 'release' or 'registry'`	Ninguno de los dos bloques está presente	Añadir al menos un bloque
`release manifest: HTTP 404 fetching ...`	URL incorrecta o el archivo aún no se ha cargado	Compruebe `release.url` y confirme que el archivo está accesible
`release manifest: no asset for darwin/arm64 in version 1.4.2`	Falta entrada de SO/arquitectura	Agregar la entrada de activo que falta a tu manifiesto.
`release manifest: asset sha256 "xyz" is not a 64-char hex digest`	Hash demasiado corto o no hexadecimal	Calcule el `sha256sum` binario y pegue el hexadecimal completo de 64caracteres
Fallo de verificación de TLS en host interno	La CA corporativa no está en el almacén de confianza del SO	Instale su CA; no hay bandera `--insecure`
Error al extraer la imagen en `agentengine dev up`	La imagen no está reflejada, o falta `docker login`	Reflejar la imagen; ejecutar `docker login <registry>` primero

Volver

TLS corporativo

variables de entorno

Fuente de artefacto personalizada (AGENTENGINE_IMAGE_SOURCE=custom)