Overview
In this guide, you can learn how to start a local development environment for your Atlas Agent Engine agent. The agentengine dev command builds a Docker image that includes your application code and starts the full agent stack, including the orchestrator, agent sandbox, tool sandbox, and a local MongoDB instance, on your machine. When the environment is running, the CLI prints the service URLs so you can develop and test your agent.
Prerequisites
Before you begin, ensure that you install the agentengine CLI. To learn more about how to install the CLI, authenticate, and register the project, see Install and Authenticate.
Optional Configuration Settings
This section describes optional settings you can use to configure your local development environment.
Enable Memory
If you set features.memory: true in your agent.yaml file, then add the following variables to your .env file before starting the local environment:
VOYAGE_API_KEY: Required for generating memory embeddings.MONGOMEM_DB_NAME: Optional. The MongoDB database name the memory server writes to. Defaults tomdb_memory_<project-id>.
Configure Local Development Settings
You can use a dev.yaml file to override local service port assignments and turn the local MongoDB instance on or off during development. Place your dev.yaml file in the same directory as your agent.yaml file. This file is optional and the platform does not add it to your .gitignore file, so you can commit and share the settings.
The following table describes the fields you can include in the dev.yaml file:
Field | Type | Required | Description |
|---|---|---|---|
| int (1–65535) | no | Port override for a platform service. Valid service names are: |
| bool | no | Whether to start a local MongoDB instance as part of the development stack. Defaults to |
| int | no | Port MongoDB listens on when running locally. Defaults to |
The following example shows a dev.yaml file that sets all available fields:
services: playground: port: 3000 oe: port: 8000 aer: port: 8001 tool: port: 8002 mongodb: local: true port: 27017
Start Local Development
The agentengine dev command supports two startup modes: hot-reload mode for active development and isolated mode for testing a production-like topology.
Hot-Reload Mode (Recommended)
Hot-reload mode runs all agent services inside a single app container and mounts your source code directly into it. When you edit a file, watchfiles detects the change and automatically reloads the affected service without requiring a full rebuild.
(Optional) Attach VS Code as a Dev Container.
If you use Visual Studio (VS) Code, perform the following steps to attach directly to the running container. This provides an integrated development experience with full IntelliSense and debugging support.
Install the Dev Containers extension in VS Code.
While the stack is running, open the Command Palette and select Dev Containers:/ Reopen in Container.
VS Code connects to the app container and reloads the workspace inside it.
Isolated Mode
You can use the --isolated flag to start the local environment in isolated mode. Isolated mode starts each agent service in a separate container, mirroring the production topology. Use this mode to validate behavior across service boundaries or to reproduce production-specific issues. Because code is not mounted from your host, you must rebuild the images after making code changes.
Manage the Local Environment
Use the following agentengine dev commands to manage your running environment.
View Logs
To stream logs from all running services, run the following command:
agentengine dev logs
To stream logs from a specific service, pass the service name as a positional argument:
agentengine dev logs <service>
In a monorepo, pass --all to stream logs for the shared all-workspaces stack:
agentengine dev logs --all
Check Local Stack Status
The agentengine dev status command shows the current state of the local compose stack, including per-service status and the published host URLs. The following example shows the command syntax:
agentengine dev status [--workspace <name>] [--all] [--json]
The following table describes the available flags:
Flag | Description |
|---|---|
| (Monorepo only) Targets a specific agent by name, as defined in the root |
| (Monorepo only) Targets the all-workspaces stack. |
| Prints a machine-readable status object to stdout. Includes |
Restart Services
The agentengine dev restart command restarts the hot-reload app and oe containers without rebuilding the image. Use this after changing dependencies on the host. The following example shows the command syntax:
agentengine dev restart [--workspace <name>]
This command targets the hot-reload stack only. It does not support --all or isolated mode.
Add New Dependencies
When you add a dependency to your pyproject.toml file, the local development stack might not install it if a uv.lock file already exists. When a uv.lock file is present, the development entrypoint syncs the environment with the --frozen flag, which resolves dependencies from the lockfile instead of from the pyproject.toml file.
To install the new dependency, run the following commands to delete the uv.lock file and restart the stack:
rm uv.lock agentengine dev stop agentengine dev up
Alternatively, you can run the following commands to update the lockfile before you restart the stack:
uv lock agentengine dev stop agentengine dev up
Use Private Artifact Repositories
If your agent depends on packages hosted in private artifact repositories, such as a private PyPI or npm registry on AWS CodeArtifact, declare them in the artifact_repositories block of your agent.yaml file. In hot-reload mode, the agentengine dev up and agentengine dev restart commands automatically configure the registry credentials for type: pypi entries. The CLI does not auto-configure npm entries. For npm private dependencies, authenticate through your local npm configuration, such as a project-level .npmrc file.
For each declared PyPI repository, provide a credential through one of the following:
A
UV_INDEX_<NAME>_PASSWORD(and optionally_USERNAME) variable in your process environment or.envfile. For example, for an index namedcorps-pypi, setUV_INDEX_CORPS_PYPI_PASSWORD.The declared
secretfield, read from your.envfile.For an AWS CodeArtifact index, a token minted from your active AWS profile or SSO session.
If no credential resolves for a declared repository, the CLI fails and names the repository and the sources to check.
To skip auto-configuration and manage UV_INDEX_* variables yourself, run the following command:
agentengine dev up --no-artifact-auth
Note
If you declare a type: pypi entry and start in --isolated or --all mode, the CLI returns an error rather than starting containers that fail at dependency installation.
To learn about the artifact_repositories schema, see Agent YAML Schema. To learn how private artifact repositories work in cloud builds, see Private Artifact Repositories.
Stop Services
To pause the local environment without removing containers, run the following command:
agentengine dev stop [--workspace <name>] [--all]
The command stops containers without removing them. Run agentengine dev up again to resume the containers without a rebuild.
Reset Local State
To stop all containers and remove all associated volumes and generated runtime files, run the following command:
agentengine dev clean [--workspace <name>] [--all]
Warning
Running agentengine dev clean permanently deletes all local data stored in the MongoDB Atlas Local volume. Back up any data you need before running this command.
After cleaning, run agentengine dev up to regenerate files and start fresh local containers.
Authenticate Remote MCP Servers
The agentengine dev mcp auth commands manage OAuth credentials for remote MCP servers configured in your agent.yaml file under mcp.servers. The commands write login credentials to the dev credential cache at ~/.agentengine/mcp-oauth, and generated agentengine dev up stacks mount that directory automatically.
The cache is separate for each project and each MCP endpoint. Logging in from one project does not log you in for another project, so you must run the agentengine dev mcp auth login command once per project. To learn about the naming requirements for MCP servers, see Server Naming Rules.
auth login
Use the agentengine dev mcp auth login command to open the provider authorization flow for a server and save credentials in the dev cache, as shown in the following example:
agentengine dev mcp auth login <server> [--no-browser]
The --no-browser flag prints the login URL instead of opening the URL in a browser.
The authorization URL that the server advertises must use the https scheme. If the server advertises an authorization endpoint that uses any other scheme, the command stops and generates a Refused to open unauthorized MCP OAuth URL error.
auth status
Use the agentengine dev mcp auth status command to check whether cached credentials exist for a server, as shown in the following example:
agentengine dev mcp auth status [server] [--check]
The --check flag uses the cached credentials to connect to the MCP server and calls the tools list endpoint to confirm that the server accepts them.
auth upload
Use the agentengine dev mcp auth upload command to base64-encode the local OAuth cache for a server and store it as a workspace secret named AGENTIC_MCP_OAUTH_B64_<SERVER>. This command exposes the authorization credentials to deployed agents.
The following example shows the command syntax:
agentengine dev mcp auth upload <server> [--workspace-id <id>] [--sync]
The --workspace-id flag specifies the workspace ID, and the``--sync`` flag reloads secrets in active deployments immediately after upload.
Before uploading, the CLI checks that the server URL recorded in the cache matches the URL in your agent.yaml file. If the cache was recorded for a different endpoint, the CLI refuses the upload and prompts you to run the agentengine dev mcp auth login command again.
Validate Configuration
The agentengine agent validate command lints your agent.yaml file locally with the same parser and validator that the build pipeline uses. Run it before building to catch typos, invalid values, and network policy errors.
The following example shows the command syntax:
agentengine agent validate [path] [--strict]
The default path is ./agent.yaml. Pass an explicit path to validate a file in a different location, such as a monorepo workspace.
The command returns the following exit codes:
Exit code | Meaning |
|---|---|
|
|
| Validation failed. The output identifies the invalid fields. |
| File or I/O error. The file could not be read. |
The command does not require authentication and can run in CI without a valid token.
When artifact_repositories is non-empty, the command cross-checks declared index names against your project tooling in the same directory as agent.yaml. For Python agents, it reads pyproject.toml and uv.lock. For TypeScript agents, it reads package.json, .npmrc, and package-lock.json. Undeclared private URLs in lockfiles are allowed, because credential injection is opt-in. The same hard errors that block cloud builds stop validation and return exit code 1.
When you are logged in, the command also prints non-blocking warnings for missing or mis-scoped artifact_repositories[].secret values, including WORKSPACE_CONTEXT_NEEDED when a workspace-scoped entry is declared without an active agentengine init context. Pass --strict to treat these warnings as exit code 1. To learn how private artifact repositories work in cloud builds, see Private Artifact Repositories.
Note
The agentengine agent validate command is experimental. Its flags, output format, and exit codes may change as the validator expands to cover more agent.yaml fields.
Next Steps
After your local environment is running, you can test the agent and iterate on your code. To learn how to manually test the agent and apply code changes, see Test the Agent.