Set Up Atlas Resources

Profile File Schema

The ~/.agentengine/atlas.json file has the following structure:

{
  "version": 1,
  "profiles": {
    "default": {
      "base_url": "https://cloud.mongodb.com",
      "client_id": "<service-account-client-id>",
      "client_secret": "<service-account-client-secret>"
    }
  }
}

You can add multiple named profiles to use with different Atlas environments or service accounts. To use a non-default profile, pass the --profile flag as shown in the following example:

agentengine atlas setup --profile <profile-name>

Environment Variables

You can supply or override credentials by using the following environment variables without editing the profile file directly:

The command resolves credentials in the following order:

1. MONGODB_ATLAS_ACCESS_TOKEN, if set

2. MONGODB_ATLAS_CLIENT_ID and MONGODB_ATLAS_CLIENT_SECRET, if both are set

3. Stored profile in ~/.agentengine/atlas.json

4. Interactive prompt, if a terminal is attached

Command Flags

Interactive Flow

When you run agentengine atlas setup, the CLI guides you through the following steps:

1. Organization: Lists your Atlas organizations with a numbered menu. Select an existing organization or create a new one.

2. Project: Lists the projects in the selected organization. Select an existing project or create a new one. New projects receive a project-scoped service account.

3. Cluster: Lists the clusters in the selected project. Select an existing cluster or, if your service account has cluster creator permissions, create a new cluster.

4. Database user: Creates a database user with the credentials that the agent uses to connect to the cluster.

5. Voyage AI API key: Provisions a Voyage AI API key for the agent's memory features.

6. Secrets: Saves MONGODB_URI and VOYAGE_API_KEY as Atlas Agent Engine secrets so that deployed agents can connect to your Atlas cluster and Voyage AI.

7. IP access list: Adds the Atlas Agent Engine data plane IP addresses to the cluster's IP access list.

After the flow completes, the CLI displays the provisioning status for each resource.

Automatic Setup

To create all Atlas resources automatically without interactive prompts, pass the --yes flag to the agentengine atlas setup command. When the workspace has not been initialized, the agentengine atlas setup --yes command runs agentengine init first, then creates the following resources by using names based on the workspace ID:

• Atlas cluster

• Database user named magenta-<workspace-id>

• Voyage API key named magenta-<workspace-id>

Automatic setup stops when it finds saved metadata or existing Atlas resources that match those generated names. To create a fresh set of resources, remove the conflicting resources and pass --force.

Automatic setup uses the saved Atlas project when present. Otherwise, it requires exactly one visible Atlas organization and one visible Atlas project to proceed without prompts.

You can override the default cluster configuration by setting the following environment variables before running the command:

Setup Status

The agentengine atlas setup command displays the provisioning status of all resources at the end of each run. To recheck the current state or rerun the full setup flow, run the following command:

agentengine atlas setup --force

List Profiles

Use the following command to return the saved profiles from the ~/.agentengine/atlas.json file:

agentengine atlas profile list --json

The following example shows the output format:

{
  "schema_version": "1",
  "status": "ok",
  "profiles": [
    {"name": "default", "base_url": "https://cloud.mongodb.com"}
  ]
}

Verify a Profile

Use the following command to validate service account credentials and return accessible organizations and projects:

agentengine atlas profile verify --json --input -

Pass a JSON request object through stdin by passing - to the --input flag. The command returns the selected profile name, base URL, and lists of accessible organizations and projects. The output does not include access tokens and secrets.

Save a Profile

Use the following command to persist the selected Atlas organization and project into the workspace context:

agentengine atlas profile save [--context <name>] [--workspace <name>] --json --input -

Pass a JSON request object through stdin by passing - to the --input flag. The command saves the Atlas environment, profile, organization, and project to the workspace's .agentengine/state.json file. If the organization and project selection does not change, the command preserves any existing cluster, database user, and Voyage API key selections.

List Clusters

Use the following command to return the clusters in the saved Atlas project:

agentengine atlas cluster list [--context <name>] [--workspace <name>] --json

The following example shows the output format:

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "clusters": [
    {
      "name": "my-cluster",
      "kind": "REPLICASET",
      "state_name": "IDLE",
      "is_flex": false
    }
  ],
  "create_defaults": {
    "name": "my-agent",
    "provider": "AWS",
    "region": "US_EAST_1",
    "tier": "FLEX",
    "label": "Flex"
  },
  "can_create": true,
  "warnings": []
}

The create_defaults object provides the suggested configuration for a new cluster. The can_create field indicates whether the service account has permission to create a cluster in the selected project.

Save a Cluster

Use the following command to select an existing cluster or create a new one:

agentengine atlas cluster save [--context <name>] [--workspace <name>] --json --input -

Pass a JSON request object through stdin by passing - to the --input flag. To select an existing cluster:

{"mode": "existing", "name": "my-cluster"}

To create a new cluster:

{
  "mode": "create",
  "name": "my-agent",
  "provider": "AWS",
  "region": "US_EAST_1",
  "tier": "FLEX"
}

If you omit the name field in create mode, the CLI generates a name from the workspace ID. Creating a cluster requests provisioning in Atlas and returns immediately. Atlas may take several minutes to finish provisioning the cluster.

List Database Users

Use the following command to return the database users in the saved Atlas project:

agentengine atlas database-user list [--context <name>] [--workspace <name>] --json

The following example shows the output format:

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "users": [
    {"username": "my-user", "database_name": "admin"}
  ],
  "create_defaults": {"username": "magenta-<workspace-id>"},
  "can_create": true,
  "warnings": []
}

When the command finds an existing user whose name matches the generated default for the workspace, it saves that user to the .agentengine/state.json file automatically. This keeps local state current when resources were provisioned outside the current session.

Save a Database User

Use the following command to select an existing user or create a new one:

agentengine atlas database-user save [--context <name>] [--workspace <name>] --json --input -

Pass a JSON request object through stdin by passing - to the --input flag. To select an existing user, include the password as shown in the following example:

{"mode": "existing", "username": "my-user", "password": "my-password"}

To create a new user, pass the following object:

{"mode": "create", "username": "my-user"}

If you omit the username field in create mode, the CLI generates a name from the workspace ID. For new users, the CLI generates a password automatically. The generated password is not included in the command output.

After saving, the command writes MONGODB_URI as a project-scoped Atlas Agent Engine secret. It does not write to a local file.

List Voyage API Keys

Use the following command to return the Voyage API keys in the saved Atlas project:

agentengine atlas voyage-api-key list [--context <name>] [--workspace <name>] --json

The following example shows the output format:

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "keys": [
    {
      "id": "key-id",
      "name": "magenta-<workspace-id>",
      "masked_secret": "voy...xxxx"
    }
  ],
  "create_defaults": {"name": "magenta-<workspace-id>"},
  "can_create": true,
  "warnings": []
}

When the command finds an existing key whose name matches the generated default for the workspace, it saves that key to the .agentengine/state.json file automatically.

Save a Voyage API Key

Use the following command to select an existing key or create a new one:

agentengine atlas voyage-api-key save [--context <name>] [--workspace <name>] --json --input -

Pass a JSON object through stdin by passing - to the --input flag. To select an existing key, use the following format:

{"mode": "existing", "name": "my-key", "value": "<api-key-value>"}

To create a new key, use the following format:

{"mode": "create", "name": "my-key"}

If you omit the name field in create mode, the CLI generates a name from the workspace ID. When you create a key, the CLI uses the Atlas-returned secret value directly.

After saving, the command writes VOYAGE_API_KEY as a project-scoped Atlas Agent Engine secret. It does not write to a local file. For lower Atlas environments, the command also writes the VOYAGE_URL variable the same way.