install-authenticate

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!-- Tab options on this page. Append to the .md URL to filter: ?tabs=<id,...> select specific tabs (e.g. ?tabs=nodejs,shell) ?allTabs=true include every tab (no param) default: one tab per tabset

Available tabs: other tabs: macos-linux, windows -->

Install and Authenticate

MongoDB Atlas Agent Engine is in Public Preview and intended for evaluation and prototyping purposes only. We do not recommend production deployments during preview and expect to communicate breaking changes with you periodically. To learn more about preview feature considerations, see Preview Features.

Overview

This tutorial shows you how to install and authenticate your account with the MongoDB Atlas Agent Engine. You will verify your system dependencies, install the agentengine CLI, verify the runner-base image, and authenticate your account against the Atlas Agent Engine API Gateway.

Prerequisites

Ensure that you have the following components installed and configured before you start this tutorial:

Use a Custom Artifact Source

You can configure the agentengine CLI to download the binary and pull agent runtime images from your own hosts instead of the MongoDB-hosted registry. Run agentengine agent source setup to generate a source.yaml file, or run agentengine agent source template to write a commented template you can edit. Run these commands after you install the agentengine CLI.

By default, the CLI reads source.yaml from ~/.agentengine/source.yaml. To use a different location, set the AGENTENGINE_IMAGE_SOURCE_FILE environment variable to the file path.

Export AGENTENGINE_IMAGE_SOURCE=custom to route agentengine dev up and agentengine self-update to your custom host. The following sample source.yaml mirrors both the CLI binary and the agent runtime images:

base: internal
release:
  type: static
  url: https://artifactory.example.com/agentic-cli/manifest.json
registry:
  prefix: artifactory.example.com/acme-docker

The release block directs CLI binary downloads to your host, and the registry.prefix block directs agent runtime image pulls to your registry. If you mirror only one of these, the CLI uses the base source, internal by default, for the other.

With type: static, the manifest at release.url must match the following structure, with one entry in assets for each OS and architecture. Otherwise, agentengine self-update fails and the CLI doesn't display update notifications.

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

To read releases from a GitHub Enterprise releases API instead of a manifest, set release.type to github and release.url to the API endpoint, such as https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releases.

If your image registry requires authentication, log in before you run agentengine dev up. For example, run docker login <registry> or, for Amazon ECR, run the following command:

aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.amazonaws.com

Install the agentengine CLI

The agentengine CLI is the primary tool for local development with the MongoDB Atlas Agent Engine. It generates the Docker Compose configuration needed to run your agent's three services locally.

The following steps describe how to download the CLI from the Atlas Agent Engine UI.

1. Open the Install CLI page.

Sign in to the Atlas Agent Engine, then download the CLI from the CLI download page.

The page displays a Version dropdown, which is pre-filled with the latest CLI version. It also displays a Platform dropdown pre-filled with your detected operating system. To change these default values, choose a different version or platform from the dropdown selectors.

1. Download the binary.

After you select a version and platform, click the Download for \<your platform> button. Save the SHA-256 checksum value that the page displays for use in the following step.

1. Verify the download.

In your terminal, navigate to your downloads directory. Select the tab corresponding to your operating system and run the following command:

### macOS / Linux

bash shasum -a 256 agentengine

The output must match the SHA-256 value that you saved. If the values don't match, delete the binary and download it again.

1. Mark the binary as executable.

Select the tab corresponding to your operating system and run the following command to mark the binary as executable:

### macOS / Linux

bash chmod +x agentengine

1. Add the binary to your PATH.

Select the tab corresponding to your operating system to view instructions for adding the binary to your PATH.

### macOS / Linux

From your downloads directory, run the following command:

bash mkdir -p ~/.local/bin mv agentengine ~/.local/bin/agentengine

Confirm that ~/.local/bin is on your PATH. Installing the binary in a user-writable directory lets you run the agentengine self-update command without using the sudo command.

1. Verify the installation.

Confirm the CLI is installed by checking its version:

bash agentengine version

The output resembles the following:

none 0.1.94-alpha (commit: <hash>) image registry: ECR runner-base: <registry-host>/runner-base:0.1.94-alpha runner-base-typescript-langgraph: <registry-host>/runner-base-typescript-langgraph:0.1.94-alpha playground-ui: <registry-host>/playground-ui:0.1.94-alpha orchestrator: <registry-host>/orchestration-engine:<version> memory-server: <registry-host>/memory-server:<version>

To learn how to update an installed CLI to a newer version, see [Update the CLI.](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-update-cli

Opt Out of Usage Analytics

By default, the agentengine CLI sends product usage analytics to the Atlas Agent Engine. The CLI doesn't send analytics for development builds or when the CI environment variable is set.

To disable usage analytics, set the AGENTENGINE_TELEMETRY_ENABLED environment variable to 0, false, no, or off.

The following command provides an example of how to disable usage analytics:

export AGENTENGINE_TELEMETRY_ENABLED=false

To learn about other environment variables that the CLI reads, see the [Environment variables](https://www.mongodb.com/docs/agentengine/cli/environment-variables.md#std-label-environment-variables CLI documentation.

Verify the Runner-Base Image

The runner-base image is the container image that the Atlas Agent Engine uses to run each of your agent's three services locally. If Docker cannot pull this image when you first run an agent, your agent fails to start. Verifing the Docker base image allows you to catch and fix any network issues before you run your agent project. Verifying your runner-base image is optional, but recommended.

Local development pulls the runner-base image from MongoDB's hosted container image registry. You don't need GitHub access or a separate registry login. The CLI uses your agentengine auth login session to retrieve the image, and prints the registry host when you run the agentengine dev up command.

1. Get the runner-base image reference.

Run the agentengine version command to retrieve the default runner-base image:

bash agentengine version

Copy the runner-base: value from the output.

1. Authenticate to the platform image registry.

Run the following command to log your local Docker installation into the platform image registry:

bash agentengine dev login

The agentengine dev up command runs this flow automatically, so this step is only required when you pull an image directly.

1. Pull the runner-base image.

Run the following command to pull the runner-base image, and replace <runner-base-image> with the value that you copied from the agentengine version output:

bash docker pull <runner-base-image>

A successful pull ends with a Status: line that reads either Downloaded newer image or Image is up to date.

Authenticate Your Account

The agentengine auth login command starts a browser-based OIDC login flow against the Atlas Agent Engine API Gateway and saves local authentication state for future CLI commands.

Note: Atlas OAuth Delegation

When you sign in to the Atlas Agent Engine, the platform automatically retrieves your role assignments from Atlas and determines which organizations and projects you can access. The platform uses the Atlas OAuth 2.1 App Connections server to authorize access to Atlas.

1. Log in to the Atlas Agent Engine.

From your terminal, run the following command:

bash agentengine auth login

By default, this opens a browser against the production API Gateway at https://agentengine.mongodb.com. You can pass --base-url to the command to target a different gateway, or pass --no-browser to print the login URL without opening a browser. The following code shows the format for the command:

bash agentengine auth login [--base-url <url>] [--no-browser] [--timeout <duration>]

After you complete sign-in, the CLI reads your project memberships from the API and persists the selected project ID project_id as well as your auth token.

1. Select a project.

If your account belongs to a single project, it's selected automatically. If your account belongs to multiple projects, the CLI prompts you to pick one interactively. If you don't have a preference, select your default project. The CLI saves your selection as a default that you can override with the --project-id flag.

1. Verify your authentication status.

To check whether your authentication succeeded, run the following command:

bash agentengine auth status

This command prints your current local auth context without contacting the platform, and its output reflects the saved login state on disk. You can pass the --json flag to the command to output a JSON object with separate auth, command_defaults, and directory_context fields.

Until you register an agent directory by running the agentengine init command, the Directory context field reports none found. A successful login still displays your account, base URL, and default organization and project.

Tip:

If your auth token expires, log out and log back in to refresh it:

agentengine auth logout
agentengine auth login

Next Steps

After installing and authenticating your account with the MongoDB Atlas Agent Engine, you can create a project. To learn how to perform these next steps, see the [Create a Project](https://www.mongodb.com/docs/agentengine/build/create-project.md#std-label-agent-engine-set-up-create-project guide.