> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Deploy commands
description: Reference for building, pushing, and deploying AGNT5 projects, and for monitoring the resulting deployments.
category: CLI
last_verified: 2026-07-24
---

**`agnt5 deploy`** is the all-in-one command that builds your project, pushes the resulting image to the configured registry, validates the target workspace, and creates (or updates) a deployment. Run it from the project root and the CLI orchestrates the rest. **`agnt5 build`** runs just the build step; **`agnt5 deployment`** inspects the current project's latest deployment.


**Command**: `agnt5 deploy [options]`
**Required**: authenticated session (`agnt5 auth login`); project binding (`.agnt5/project-ref`); deployment manifest (`agnt5.yaml`)
**Key flags**: `--env`, `--replicas`, `--min-replicas`, `--max-replicas`, `--max-run-duration`, `--dry-run`, `--no-wait`, `--workspace`, `--platform`, `--registry`
**Not flags**: `--prod`, `--staging`, `--cpu`, `--memory`, and `--tags` do not exist on `agnt5 deploy`. Use `--env production` to target production. Worker CPU/memory are platform-managed and not user-configurable. Extra image tags belong to `agnt5 build --tags`.
**Side effects**: builds a Docker image or code bundle; pushes to the configured registry; creates/updates a Control Plane deployment
**Stages**: dry-run plan (optional) → build → push → deploy → wait for ready


## Prerequisites

- You must be authenticated (`agnt5 auth login`) so the CLI can talk to the Control Plane and container registries.
- The working directory needs a project binding via `.agnt5/project-ref` and a deployment manifest (`agnt5.yaml`). `agnt5 create <name>` scaffolds both in a new directory; `agnt5 init` does the same in the current directory.
- Dockerfile-based builds use a local Docker/BuildKit daemon when one is available; pass `--use-managed-builder` to build on the platform's managed BuildKit instead. Code-bundle deployments upload your source directly and need no local Docker.

## `agnt5 deploy`

```bash
agnt5 deploy [options]
```

The complete deployment workflow, in four stages:

1. **Pre-flight validation** — verifies control-plane connectivity, project binding, and the `agnt5.yaml` schema. Skip with `--skip-validation` (useful in CI).
2. **Dry run (optional)** — with `--dry-run` the CLI prints a deployment preview and exits without building or deploying.
3. **Build** — builds a Docker image (Dockerfile path) or prepares a code bundle, then pushes to the configured registry.
4. **Deploy** — issues the deployment request to the Control Plane and, unless `--no-wait` is set, waits for the deployment to become ready.

### Common options

| Flag | Description |
| --- | --- |
| `--env <environment>` | Target environment. Default: `preview`. Pass `--env production` to deploy to production; the CLI asks for confirmation in interactive mode. |
| `--dry-run` | Validate configuration and show what would be deployed without executing. |
| `--no-wait` | Return as soon as the deployment is created, without waiting for it to become ready. |
| `--wait-timeout <duration>` | How long to wait for the deployment to become ready. Default: `5m`. Ignored with `--no-wait`. |
| `--verbose`, `-v` | Show verbose output including build logs. |

### Scaling options

| Flag | Description |
| --- | --- |
| `--replicas <n>` | Number of worker replicas. Default: `1`. Used alone, it pins a fixed pool: min and max replicas follow it. |
| `--min-replicas <n>` | Minimum number of replicas for autoscaling. Default: `1`. |
| `--max-replicas <n>` | Maximum number of replicas for autoscaling. Default: `1`; the platform caps this at `10`. |
| `--max-run-duration <duration>` | Maximum running time for workers (`30m`, `1h`, `forever`). When omitted, production and staging run with no limit; other environments cap at `1h`. |

### Build options

| Flag | Description |
| --- | --- |
| `--platform <platform>` | Build platform. Default: `linux/amd64`. |
| `--registry <url>` | Container registry URL. Auto-detected based on context. |
| `--buildkit-url <url>` | Custom BuildKit URL, e.g. `tcp://buildkit-server:1234`. |
| `--use-managed-builder` | Force the managed BuildKit builder instead of local Docker. |
| `--force-dockerfile` | Force a Dockerfile-based build even for code-bundle projects. |
| `--force-code-bundle` | Force a code-bundle deployment even when a Dockerfile exists. |
| `--base-image <image>` | Override the default base image for code-bundle deployments. |

### Workspace options

| Flag | Description |
| --- | --- |
| `--workspace <id\|name>` | Deploy to a specific workspace. |
| `--list-workspaces` | List available workspaces and exit. |
| `--interactive` | Enable interactive workspace selection and confirmation prompts. Default: `true`. |

### Validation options

| Flag | Description |
| --- | --- |
| `--connect-timeout <duration>` | Timeout for the control-plane connectivity check. Default: `10s`. |
| `--skip-validation` | Skip pre-flight validation (useful for CI/CD pipelines). |

<Callout type="info">
`agnt5 deploy` has no `--cpu`, `--memory`, or `--tags` flags. Worker CPU and memory are managed by the platform (see [Worker resources](#worker-resources)), and extra image tags are set with **agnt5 build** `--tags`.
</Callout>

```bash
# Deploy to the default preview environment
agnt5 deploy

# See the deployment plan without deploying
agnt5 deploy --env production --replicas 3 --dry-run

# Deploy to production with a fixed pool of 3 replicas
agnt5 deploy --env production --replicas 3

# Autoscale between 2 and 6 replicas
agnt5 deploy --min-replicas 2 --max-replicas 6

# Non-interactive production deploy (CI)
agnt5 deploy --env production --interactive=false --skip-validation

# Create the deployment without waiting for workers to become ready
agnt5 deploy --no-wait
```

## Scaling and replicas

Replica counts are controlled entirely by flags — there is no replica setting in `agnt5.yaml`.

- **Fixed pool**: `--replicas N` alone pins min and max to `N`, so the deployment runs exactly `N` workers.
- **Autoscaling range**: `--min-replicas` and `--max-replicas` set the bounds; the pool starts at the minimum.

<Callout type="warning">
The platform caps a deployment at **10 replicas**. Values above 10 are clamped server-side, and the CLI prints a warning before deploying.
</Callout>

## Worker resources

Worker CPU and memory are managed by the platform per environment — they are **not user-configurable**. There are no `--cpu`/`--memory` flags, and a `deploy.resources` block in `agnt5.yaml` is not applied (the CLI warns and ignores it). Current platform-managed values:

| Environment | CPU (request / limit) | Memory (request / limit) |
| --- | --- | --- |
| production | 250m / 1000m | 256Mi / 1Gi |
| all others | 100m / 500m | 128Mi / 512Mi |

These values are set by the Control Plane and may change without a CLI update. If your workload needs different limits, contact support.

## Registry pushes

After a successful build, the CLI tags and pushes the image for the configured registry:

- The registry is auto-detected from your context configuration; the default remote registry is `cr.agnt5.com`.
- Pass `--registry` to push to a specific registry URL instead.
- Authentication uses your AGNT5 API key.

## Workspace validation and deployment

The deployment step uses the Control Plane API to ensure your workspace is ready:

| State | Action |
| --- | --- |
| **No workspace** | CLI creates one automatically and waits for it to reach the `ready` phase. |
| **Paused** | Workspaces are resumed before deployment. |
| **Pending/Provisioning** | Triggers a wait loop until ready. |
| **Failed** | Produces actionable error messages and stops the deployment. |

When the workspace is ready the CLI issues the deployment request with your image reference and replica settings, then streams progress until the deployment reaches a ready status (or `--wait-timeout` elapses). Upon success it prints follow-up steps, including how to tail logs with `agnt5 logs`.

## `agnt5 build`

```bash
agnt5 build [options]
```

Builds and pushes a Docker image without deploying it — useful for building in CI and deploying the result separately, or for testing the build step in isolation.

| Flag | Description |
| --- | --- |
| `--project-dir <path>` | Project directory. Default: `.`. |
| `--no-push` | Build without pushing to the registry. |
| `--tags <tag,tag,...>` | Additional image tags, e.g. `v1.0.0,latest`. |
| `--build-args <key=value>` | Build arguments passed as environment variables. Repeatable. |
| `--platform <platform,...>` | Target platforms. Default: `linux/amd64`. Multi-platform builds require pushing. |
| `--registry <url>` | Container registry URL. |
| `--buildkit-url <url>` | Custom BuildKit URL, e.g. `tcp://buildkit-server:1234`. |
| `--use-managed-builder` | Force the managed BuildKit builder instead of local Docker. |
| `--verbose`, `-v` | Show verbose output including container logs. |

```bash
agnt5 build
agnt5 build --tags v1.0.0,latest
agnt5 build --no-push --platform linux/arm64
```

## `agnt5 deployment`

```bash
agnt5 deployment <command>
```

Inspects the **current project's latest deployment** — resolved from the local `.agnt5/project-ref`, no deployment ID needed. This is different from `agnt5 deploy status <id>`, which targets a specific deployment by ID.

- **`agnt5 deployment status`** — Status, replica counts, and uptime. `--watch`/`-w` refreshes every 2 seconds.
- **`agnt5 deployment errors`** — Kubernetes warning events for the deployment (scheduling failures, image pull errors, crash loops). `--since <window>` limits the window, e.g. `1h`, `30m`, `7d`.

```bash
agnt5 deployment status --watch
agnt5 deployment errors --since 1h
```

## Monitor a deployment

- **agnt5 deploy status** `<deployment-id>` — check the status of a specific deployment; add `--watch` to follow provisioning.
- **agnt5 deploy debug** `<deployment-id>` — show the deployment timeline and diagnostics; add `--trace <trace-id>` to look up by trace instead, `--logs` to include container logs for failed pods.
- **agnt5 deployment status** / **agnt5 deployment errors** — status and error events for the current project's latest deployment, no ID required.
- **agnt5 logs** `<deployment-id>` — tail worker logs.

## Complete example workflow

```bash
# 1. Check the deployment plan
agnt5 deploy --env production --replicas 3 --dry-run

# 2. Build and deploy to production
agnt5 deploy --env production --replicas 3

# 3. Monitor the rollout
agnt5 deploy status <deployment-id> --watch
agnt5 logs <deployment-id>
```

<Callout type="tip">
Use `--dry-run` first to verify the deployment plan, then run the full command. Combine with **agnt5 deploy status** and **agnt5 logs** to monitor the rollout.
</Callout>



## Next steps

- [Inspect & logs](/docs/cli/inspect.md): dig into runs, traces, and logs after a deploy.
- [Serverless commands](/docs/cli/serverless.md): deploy to a provider-hosted endpoint instead.
- [Configuration](/docs/cli/configuration.md): registry, context, and environment settings.
- [Troubleshooting](/docs/cli/troubleshooting.md): common deploy failures and fixes.