> This page location: /docs.md > /docs/agentengine.md

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

# Deploy Your Build

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](https://www.mongodb.com/docs/preview-features/).

## 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.](https://www.mongodb.com/docs/agentengine/deploy/agent-image.md#std-label-agent-engine-deploy-agent-image)

## Command Syntax and Options

Use the following commands to manage your deployment:

- [agentengine deploy](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build-start)

- [agentengine deploy list](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build-list)

- [agentengine deploy get \<deployment\_id>](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build-status)

- [agentengine deploy logs \<deployment\_id>](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build-logs)

- [agentengine deploy cancel \<deployment\_id>](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build-cancel)

### Start a Deployment

Use the following syntax to deploy your agent build:

```bash
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 |
| --- | --- |
| `--auto` | 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. |
| `--build-id` | The build ID to deploy. By default, the command deploys the workspace's last successful build. This flag is mutually exclusive with `--version`. |
| `--version` | Deploys the release build for this declared `agent.yaml` version. This flag is mutually exclusive with `--build-id`. |
| `--workspace-id` | The platform workspace ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--project-id` | The platform project ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--org-id` | The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| `--base-url` | The platform API base URL. |
| `--context` | The named local context from the `.agentengine/state.json` file. |
| `--no-wait` | Instructs the CLI to return immediately after starting the deployment without polling for status. |
| `--timeout` | The maximum time to wait for the deployment to complete. By default, the deployment times out after 30 minutes. |
| `--workspace` | *(Monorepo only)* Deploys a specific workspace by name, as defined in the root `agent.yaml`. This flag is mutually exclusive with `--all`. |
| `--all` | *(Monorepo only)* Deploys all workspaces sequentially. This flag is mutually exclusive with `--workspace`. |
| `--json` | Outputs the deployment result as JSON. |
| `--yes` | 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:

```bash
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 |
| --- | --- |
| `--workspace` | *(Monorepo only)* Selects a specific workspace by name, as defined in the root `agent.yaml`. |
| `--workspace-id` | The platform workspace ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--project-id` | The platform project ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--org-id` | The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| `--base-url` | The platform API base URL. |
| `--context` | The named local context from the `.agentengine/state.json` file. |
| `--status` | Filters results by deployment status, for example `succeeded`, `failed`, or `in_progress`. |
| `--limit` | The maximum number of deployments to return. |
| `--offset` | The number of deployments to skip. |
| `--json` | Outputs the deployment list as JSON. |

### Check Deployment Status

To view the detailed status of a deployment, run the following command:

```bash
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 |
| --- | --- |
| `-f`, `--follow` | 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. |
| `--workspace` | *(Monorepo only)* Selects a specific workspace by name. |
| `--workspace-id` | The platform workspace ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--project-id` | The platform project ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--org-id` | The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| `--base-url` | The platform API base URL. |
| `--context` | The named local context from the `.agentengine/state.json` file. |
| `--json` | Outputs the deployment status as JSON. |

### View Deployment Event Log

To view the structured event log for a deployment, run the following command:

```bash
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 |
| --- | --- |
| `-f`, `--follow` | Polls for new events until the deployment reaches a terminal state. |
| `--severity` | Filters events by severity level: `info`, `success`, `warn`, or `error`. |
| `--category` | Filters events by category, for example `agent_rollout` or `tool_rollout`. |
| `--limit` | The maximum number of events to return per page. Defaults to 100. |
| `--workspace` | *(Monorepo only)* Selects a specific workspace by name. |
| `--workspace-id` | The platform workspace ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--project-id` | The platform project ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--org-id` | The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| `--base-url` | The platform API base URL. |
| `--context` | The named local context from the `.agentengine/state.json` file. |
| `--json` | Outputs the event log as JSON. |

### Cancel a Deployment

To cancel a deployment that's in progress, use the following command:

```bash
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 |
| --- | --- |
| `--workspace` | *(Monorepo only)* Selects a specific workspace by name, as defined in the root `agent.yaml` file. |
| `--workspace-id` | The platform workspace ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--project-id` | The platform project ID. By default, the CLI reads this value from the `.agentengine/state.json` file. |
| `--org-id` | The organization ID. By default, the CLI reads this value from your locally stored authentication state. |
| `--base-url` | The platform API base URL. |
| `--context` | The named local context from the `.agentengine/state.json` file. |

## 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.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-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.

1. Start a deployment.

   Run the following command to deploy the last successful build and return immediately without polling for status:

   ```bash
   agentengine deploy --no-wait
   ```

   If the deployment starts successfully, the output resembles the following:

   ```none
   Deploying last successful build...
   ✓ Deployment started (deployment_id: deploy-9fb9e685)
   ```

2. Check the status of the deployment.

   Run the following command to check the deployment status by using the deployment ID from the previous step:

   ```bash
   agentengine deploy get deploy-9fb9e685
   ```

   The output resembles the following:

   ```none
   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
   ```

3. Cancel the deployment.

   Finally, run the following command to cancel the deployment:

   ```bash
   agentengine deploy cancel deploy-9fb9e685
   ```

## Next Steps

After deploying your agent, you can monitor its performance and activity. To learn how to monitor your agent, see the [Monitor](https://www.mongodb.com/docs/agentengine/manage/monitor.md#std-label-agent-engine-monitor) guide.

To learn about the minimum requirements for running an agent on the Atlas Agent Engine, see the [Agent Contract](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-agent-contract) section of the MongoDB Atlas Agent Engine documentation.
