Custom artifact source (AGENTENGINE_IMAGE_SOURCE=custom)

How it works

Two independent knobs, each optional:

Custom source swaps only the host — image repository names and tags stay baked at build time, so your mirror can copy mechanically: same names, same tags, your host.

The five dev-stack images are: playground-ui, orchestration-engine, memory-server, runner-base, runner-base-typescript-langgraph.

Prerequisites

• AGENTENGINE_IMAGE_SOURCE=custom in your environment

• source.yaml at ~/.agentengine/source.yaml (or at a path set in $AGENTENGINE_IMAGE_SOURCE_FILE)

• Your corporate CA must be in the OS trust store — there is no --insecure flag (see Security)

Step 1 — Get image names and tags

Run agentengine version --full to get the exact image names and tag for the current CLI build:

agentengine version --full

Example output:

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

Use these exact names and tags when mirroring. They are stable across patch releases within a major version; only the version suffix changes.

Step 2 — Mirror images (if mirroring the dev stack)

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

Repeat for each new CLI version. Repository names and the tag format are stable; only the version number changes.

Step 3 — Host the CLI binary (if mirroring binary downloads)

If your network also blocks GitHub releases, host the CLI binaries on an HTTPS server (an Artifactory generic repository works well) and publish a manifest.json matching the static manifest format.

Upload the binary files for each OS/arch combination, then create the manifest pointing at them. The manifest URL becomes release.url in source.yaml.

Step 4 — Write source.yaml

Place at ~/.agentengine/source.yaml, or at the path you set in $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

Step 5 — Verify

agentengine agent source validate checks the file without requiring $AGENTENGINE_IMAGE_SOURCE to be set first, and on success prints the exact env vars to activate it:

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

Validation failures surface the same pinned messages listed in Troubleshooting below, whether the file came from agentengine agent source setup, agentengine agent source template, or hand-editing.

Then activate it and confirm the resolved routing:

export AGENTENGINE_IMAGE_SOURCE=customagentengine version --full

For a full mirror you should see:

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

The images in the output are the exact strings passed to docker pull by agentengine dev up.

Then run agentengine self-update to test the binary update path, and agentengine dev up to confirm image pulls succeed.

Static release manifest format

The CLI fetches this file from release.url, picks the highest semver version, and selects the asset matching the current OS and architecture. There is no latest field — the CLI computes the maximum version from the releases array, so a stale pointer can never disagree with the available assets.

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

The CLI validates that sha256 is a 64-character hex string at parse time and re-verifies the downloaded binary before installation.

Security

HTTPS is required, no ``--insecure`` override. SHA-256 verifies the binary matches the manifest, but nothing cryptographically signs the manifest itself. Over plain HTTP an attacker can rewrite both the download URL and the hash together and verification still passes. TLS is the only manifest-integrity guarantee. On-premises release servers must use TLS.

Corporate CA. Air-gapped enterprises typically run an internal certificate authority. The CLI uses Go’s TLS stack, which follows the OS certificate trust store. Your corporate CA must be installed in the OS trust store before using AGENTENGINE_IMAGE_SOURCE=custom with an internal HTTPS host. There is no --insecure or --cacert flag. A TLS verify failure against an internal host is a trust-store problem, not a CLI bug.

Package installs inside the generated local-dev image are a separate trust store. See Corporate TLS inspection in local agentengine dev up.

Registry authentication. The CLI never stores or manages Docker credentials. If your registry requires authentication, run docker login <registry> once before running agentengine dev up. The CLI passes image references to Docker, which uses its own ambient credential store.

``source.yaml`` discovery. The CLI loads source.yaml only from $AGENTENGINE_IMAGE_SOURCE_FILE (when set) or ~/.agentengine/source.yaml. It never auto-loads from the current working directory — doing so would allow a cloned repository to redirect self-update to an attacker-controlled host.

Troubleshooting