Overview
In this guide, you can learn how to deploy your agent build to production from the CLI. Before deploying, ensure that you build the agent image.
Command Syntax and Options
Use the following commands to manage your deployment:
Start a Deployment
Use the following syntax to deploy your agent build:
agentengine deploy [--auto] [--build-id <id>] [--version <version>] [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>] [--no-wait] [--timeout <duration>] [--workspace <name>] [--all] [--json] [--yes]
This command starts a deployment of your last successful build or a specific build if you provide a build ID. The command polls deployment status every 5 seconds until the deployment has a succeeded, failed, or rolled_back status, or the timeout value is reached.
Important
Filesystem Access
After deploying your agent, ensure that you write local files only under the /tmp or /scratch directories. Do not use other paths such as /var or home directories, because they might not be writable in the runtime environment.
Command Flags
When deploying your build, you can use the following optional flags:
Flag | Description |
|---|---|
| Builds the agent and monitors the deployment that the build triggers. This flag applies to single-agent projects only. Use this flag to build and deploy in one step instead of running the two commands separately. |
| The build ID to deploy. By default, the command deploys the workspace's last successful build. This flag is mutually exclusive with |
| Deploys the release build for this declared |
| The platform workspace ID. By default, the CLI reads this value from the |
| The platform project ID. By default, the CLI reads this value from the |
| The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| The platform API base URL. |
| The named local context from the |
| Instructs the CLI to return immediately after starting the deployment without polling for status. |
| The maximum time to wait for the deployment to complete. By default, the deployment times out after 30 minutes. |
| (Monorepo only) Deploys a specific workspace by name, as defined in the root |
| (Monorepo only) Deploys all workspaces sequentially. This flag is mutually exclusive with |
| Outputs the deployment result as JSON. |
| Accepts billed Flex defaults and Atlas IP access-list changes when the deploy command runs the Atlas setup. |
List Deployments
To view the deployment history for your workspace, run the following command:
agentengine deploy list [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>] [--status <status>] [--limit <n>] [--offset <n>] [--json]
This command displays all deployments for the current workspace, including the deployment ID, status, executor, build ID, image, creation time, version, and error message.
Command Flags
Flag | Description |
|---|---|
| (Monorepo only) Selects a specific workspace by name, as defined in the root |
| The platform workspace ID. By default, the CLI reads this value from the |
| The platform project ID. By default, the CLI reads this value from the |
| The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| The platform API base URL. |
| The named local context from the |
| Filters results by deployment status, for example |
| The maximum number of deployments to return. |
| The number of deployments to skip. |
| Outputs the deployment list as JSON. |
Check Deployment Status
To view the detailed status of a deployment, run the following command:
agentengine deploy get [<deployment_id>] [-f] [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>] [--json]
By default, this command returns a point-in-time snapshot of the most recent deployment. Provide a deployment ID to check a specific deployment. The output includes the deployment status, build ID, version, image, conditions, component readiness, and live health information.
Command Flags
Flag | Description |
|---|---|
| Stream deployment events in real time by using Server-Sent Events (SSE) until the deployment reaches a terminal state. If the deployment is already in a terminal state, the command reports that there is nothing to stream. |
| (Monorepo only) Selects a specific workspace by name. |
| The platform workspace ID. By default, the CLI reads this value from the |
| The platform project ID. By default, the CLI reads this value from the |
| The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| The platform API base URL. |
| The named local context from the |
| Outputs the deployment status as JSON. |
View Deployment Event Log
To view the structured event log for a deployment, run the following command:
agentengine deploy logs [<deployment_id>] [-f] [--severity <level>] [--category <category>] [--limit <n>] [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>] [--json]
This command retrieves the event log for the specified deployment, showing each state transition from creation through completion. If you do not provide a deployment ID, the command shows the event log for the most recent deployment. You can use the event log to trace deployment behavior, investigate failures, and verify that expected lifecycle transitions occurred.
When a deployment does not succeed, the event for the failing component includes both an exit code and a brief reason for the failure.
Note
The --json flag cannot be combined with the --follow, --severity, or --category flags.
Command Flags
Flag | Description |
|---|---|
| Polls for new events until the deployment reaches a terminal state. |
| Filters events by severity level: |
| Filters events by category, for example |
| The maximum number of events to return per page. Defaults to 100. |
| (Monorepo only) Selects a specific workspace by name. |
| The platform workspace ID. By default, the CLI reads this value from the |
| The platform project ID. By default, the CLI reads this value from the |
| The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| The platform API base URL. |
| The named local context from the |
| Outputs the event log as JSON. |
Cancel a Deployment
To cancel a deployment that's in progress, use the following command:
agentengine deploy cancel <deployment_id> [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>]
This command returns an error if the deployment is already in a succeeded, failed, or rolled_back state.
Command Flags
Flag | Description |
|---|---|
| (Monorepo only) Selects a specific workspace by name, as defined in the root |
| The platform workspace ID. By default, the CLI reads this value from the |
| The platform project ID. By default, the CLI reads this value from the |
| The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| The platform API base URL. |
| The named local context from the |
Build Limits
The platform enforces the following build limits for each project:
Limit | Value |
|---|---|
Concurrent active builds | 10 |
Daily builds over a rolling 24-hour period | 100 |
If you exceed a build 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.
Example
The following example shows how to deploy the last successful build, check the status of that deployment, and then cancel it.
Start a deployment.
Run the following command to deploy the last successful build and return immediately without polling for status:
agentengine deploy --no-wait
If the deployment starts successfully, the output resembles the following:
Deploying last successful build... ā Deployment started (deployment_id: deploy-9fb9e685)
Check the status of the deployment.
Run the following command to check the deployment status by using the deployment ID from the previous step:
agentengine deploy get deploy-9fb9e685
The output resembles the following:
Deployment: deploy-9fb9e685 Status: in_progress (started 45s ago) Trigger: build Build: bld_01... Version: v0.1.0 (r1) Conditions: Available False NotAvailable ā One or more components are not available. Components: Orchestration Engine 0/1 not ready Agent Sandbox 1/1 ready Tool Sandbox 1/1 ready Health: unavailable
Next Steps
After deploying your agent, you can monitor its performance and activity. To learn how to monitor your agent, see the Monitor guide.
To learn about the minimum requirements for running an agent on the Atlas Agent Engine, see the Agent Contract section of the MongoDB Atlas Agent Engine documentation.