Provision Cloud Secrets

Overview

In this guide, you can learn how to perform the first step in the deployment process: setting secrets for deployed workspaces in the AWS Secrets Manager. These secrets are used to authenticate and access the resources required for cloud deployment.

Secret Syntax and Options

Use the following syntax to set secrets in the CLI, which saves them in the AWS Secrets Manager:

agentengine secret set NAME VALUE [--description <text>] [--sync] [--project-scope | --workspace-scope] [--org-id <id>] [--project-id <id>] [--workspace-id <id>]

The following table lists the secret values that are required for some or all deployments:

Secret	Description
`MONGODB_URI`	The connection string for your MongoDB deployment. This key is required for all deployments.
LLM Key	The private key for your LLM provider credentials. The available keys are `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, and `CEREBRAS_API_KEY`. You must set at least one of these values.
`VOYAGE_API_KEY`	The private key for your Voyage AI credentials. This key is required if `features.memory` is set to `true` in your `agent.yaml` file. It is also required for all TypeScript agent deployments.
`MONGOMEM_DB_NAME`	Optional. The MongoDB database name the memory server writes to. Defaults to `mdb_memory_<project-id>`. Set this secret to customize the database name used for memory storage.

Tip

If you run agentengine atlas setup, the CLI sets the MONGODB_URI and VOYAGE_API_KEY secrets automatically.

If you configure other secrets, ensure that the secret names meet the following requirements:

Use only uppercase letters, digits, and underscores
Do not start values with AGENTIC_PLATFORM_, because this prefix is reserved for platform-injected variables
Do not use the following reserved names: RUNNER_MODE, APP_ID, ORG_ID, GROUP_ID, AER_ENDPOINT, or TOOL_ENDPOINT
Use a maximum of 128 characters

If your agent.yaml file declares artifact_repositories entries, set each entry's secret value by using agentengine secret set with the same naming rules. To learn more, see Private Artifact Repositories.

Command Flags

When setting secrets, you can use the following optional flags:

Flag	Description
`--description`	Human-readable description of the secret.
`--sync`	Syncs the secrets to your deployments after setting them.
`--project-scope`	Targets project-scoped secrets, shared across all workspaces in the project. This is the default.
`--workspace-scope`	Targets a workspace-scoped secret instead of a project-scoped secret.
`--org-id <id>`	Targets a specific organization ID directly.
`--project-id <id>`	Targets a specific project ID directly.
`--workspace-id <id>`	Targets a specific workspace ID directly.

Delete a Secret

Use the following syntax to permanently delete a secret from the AWS Secrets Manager:

agentengine secret delete NAME [--yes] [--project-scope | --workspace-scope] [--org-id <id>] [--project-id <id>] [--workspace-id <id>]

Before asking you to confirm, the CLI looks up the target organization, project, and, for workspace-scoped secrets, the workspace from the server. The confirmation prompt shows their names and IDs so that you see the resolved destination rather than the values in your local files. If a name lookup fails, the prompt shows only the ID.

To skip the confirmation prompt in a script, use the --yes flag. The CLI still prints the target. Without the --yes flag, the command fails in a non-interactive environment instead of deleting the secret.

Warning

You cannot undo a secret deletion. Deployments that read the secret do not succeed until you set the secret again.

Limits on Secrets

The platform enforces the following limits on secrets:

Scope	Limit
Per project	100
Per workspace	100

If you exceed a secret limit, the request returns a 400 Bad Request error with a RESOURCE_LIMIT_EXCEEDED message.

To review all limitations that apply during Public Preview, see MongoDB Atlas Agent Engine Limitations.

Configure Atlas Network Access

If your MONGODB_URI points to an Atlas cluster, run the agentengine atlas setup command. The CLI automatically adds the Atlas Agent Engine data plane IP addresses to the cluster's IP access list so that the deployed agent can connect to your cluster.

For more information on Atlas setup, see the Set Up Atlas Resources page.

Configuration Example

The following example shows how to configure your MongoDB URI, Anthropic API key, and Voyage API key from the CLI. To set these secrets, run the following commands from your terminal:

agentengine secret set MONGODB_URI 'mongodb+srv://example.mongodb.net'
agentengine secret set ANTHROPIC_API_KEY sk-ant-api-test-key
agentengine secret set VOYAGE_API_KEY sk-voy-api-test-key

Then, run the following command to sync the secrets to all running deployments:

agentengine secret sync

Alternatively, you can set and sync your secrets in a single command by using the --sync flag, as shown in the following example:

agentengine secret set MONGODB_URI 'mongodb+srv://example.mongodb.net' --sync

Next Steps

After you provision secrets, declare which secrets each tool can access in your agent.yaml file. To learn more, see Agent YAML Schema in the Agent Contract Reference.

To prepare for cloud deployment, build the agent image. To learn more, see the Build the Agent Image guide.

Back

Set Up Atlas Resources

Build the Agent Image