> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-05-13
title: Deployment Commands
category: CLI
description: Build, push, and deploy AGNT5 projects with comprehensive deployment pipeline
---

`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. It intentionally mirrors the Vercel CLI's single entry point: run `agnt5 deploy` from the project root and the CLI orchestrates the rest.


**Command**: `agnt5 deploy [options]`
**Required**: authenticated session (`agnt5 auth login`); project binding (`.agnt5/project-ref`); deployment manifest (`agnt5.yaml`); running Docker daemon
**Key flags**: `--environment`, `--prod`, `--staging`, `--dry-run`, `--build-only`, `--platform`, `--replicas`, `--cpu`, `--memory`, `--push-remote`
**Side effects**: builds Docker image; pushes to local registry (and remote if `--push-remote`); creates/updates Control Plane deployment
**Stages**: dry-run plan (optional) → build → push → deploy


## 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 project create` scaffolds both for Python projects
- Docker must be installed and running; the CLI performs connectivity checks and will error out with guidance if Docker or the registry cannot be reached

### `agnt5 deploy`

<CommandLayout command="deploy">
  <div slot="documentation">
    The complete deployment workflow with build, push, and deployment orchestration.

    ### Syntax
    ```bash
    agnt5 deploy [options]
    ```

    ### Command Workflow

    1. **Dry run (optional)** – With `--dry-run` the CLI prints a deployment plan and exits without building or deploying
    2. **Build** – Creates a Docker context, optionally generates a Dockerfile for Python projects, and uses the local Docker daemon to build the image
    3. **Push** – Tags are pushed to the local registry by default, and optionally mirrored to a remote registry when `--push-remote` is set
    4. **Deploy** – The Control Plane client validates or creates the workspace, resumes it if paused, and issues a deployment request

    ### Options

    **Common Options**
    | Flag | Description |
    | --- | --- |
    | `--project-dir` | Use a different directory as the build context (default: `.`) |
    | `--environment` | Name of the deployment environment (default: `development`) |
    | `--prod` | Shorthand flag that forces `environment` to `production` |
    | `--staging` | Shorthand flag that forces `environment` to `staging` |
    | `--dry-run` | Show the plan without building or deploying |
    | `--build-only` | Stop after a successful build/push so you can deploy later |

    **Build Options**
    | Flag | Description |
    | --- | --- |
    | `--dockerfile` | Path to the Dockerfile (defaults to `./Dockerfile`) |
    | `--no-cache` | Disable Docker layer caching |
    | `--clean-cache` | Prune Docker build cache before building |
    | `--pull` | Always attempt to pull newer base images |
    | `--platform` | Target platforms for multi-arch builds |
    | `--build-args` | Additional build arguments |
    | `--target` | Build a specific stage from multi-stage Dockerfile |
    | `--tags` | Append extra image tags |

    **Registry Options**
    | Flag | Description |
    | --- | --- |
    | `--push` | Push to local registry (default: `true`) |
    | `--push-remote` | Mirror to remote registry |

    **Deployment Options**
    | Flag | Description |
    | --- | --- |
    | `--replicas` | Number of replicas (default: `1`) |
    | `--cpu` | CPU limit |
    | `--memory` | Memory limit |
  </div>

  <div slot="examples">
    <Tabs defaultValue="basic">
      <TabsList>
        <TabsTrigger value="basic">Basic deployment</TabsTrigger>
        <TabsTrigger value="build">Build customization</TabsTrigger>
        <TabsTrigger value="production">Production</TabsTrigger>
        <TabsTrigger value="dryrun">Dry run</TabsTrigger>
      </TabsList>

      <TabsContent value="basic">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Deploy to development environment
          agnt5 deploy
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting deployment...
          ✓ Docker connectivity check passed
          ✓ Project reference found: acme/my-project
          ✓ Building image: localhost:5001/acme/my-project:latest

          Building Docker image...
          [+] Building 45.2s (12/12) FINISHED
          ✓ Image built successfully

          ✓ Pushing to local registry
          ✓ Validating workspace (development)
          ✓ Deploying to workspace

          Deployment successful!

          Next steps:
            curl http://localhost:8090/call -d '{"serviceName":"my-project"}'
            agnt5 logs
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Deploy to staging
          agnt5 deploy --staging
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="build">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Clean build without cache
          agnt5 deploy --clean-cache
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting deployment with clean cache...
          ✓ Pruning Docker build cache
          ✓ Pulling fresh base images

          Building Docker image...
          [+] Building 120.5s (12/12) FINISHED
          ✓ Clean build completed
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Multi-platform build
          agnt5 deploy --platform linux/amd64,linux/arm64
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Build only (no deployment)
          agnt5 deploy --build-only
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="production">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Full production deployment
          agnt5 deploy --prod --replicas 3 --cpu 1 --memory 1Gi --tags v1.2.0
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting production deployment...
          ✓ Environment: production
          ✓ Replicas: 3
          ✓ Resources: 1 CPU, 1Gi memory
          ✓ Additional tags: v1.2.0

          Building Docker image...
          [+] Building 52.1s (12/12) FINISHED
          ✓ Image tagged: v1.2.0

          ✓ Pushing to local registry
          ✓ Mirroring to remote registry
          ✓ Validating production workspace
          ✓ Deploying with 3 replicas

          Production deployment successful!

          Deployment ID: dep-prod-abc123
          Status: running (3/3 replicas ready)
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="dryrun">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # See deployment plan
          agnt5 deploy --dry-run
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Deployment Plan (DRY RUN):

          Project: acme/my-project
          Environment: development
          Image: localhost:5001/acme/my-project:latest
          Replicas: 1
          Resources: default

          Build Steps:
          1. Validate Docker connectivity
          2. Build image from ./Dockerfile
          3. Push to localhost:5001

          Deploy Steps:
          1. Validate/create development workspace
          2. Deploy with 1 replica
          3. Wait for ready status

          No changes will be made (dry run mode).
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Plan production deployment
          agnt5 deploy --prod --dry-run --replicas 3
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

## Build Stage Details

The build stage performs several safeguards before issuing a Docker build:

- Validates Docker connectivity by pinging the daemon and pulling a tiny `hello-world` image to confirm registry access
- Ensures Docker is installed, the project directory exists, and a Dockerfile is available (generating one for Python projects when needed)
- Reads defaults from `config.yaml`/`agnt5.yaml` to name the image after your project reference and merges in any additional tags or build arguments you provided

<Callout type="info">
If you set `--clean-cache` or `--no-cache`, the CLI prunes the Docker build cache before starting the build and forces base image pulls. Progress updates stream directly to the terminal (including the current Docker build step).
</Callout>

## Registry Pushes

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

### Local Registry
- Local pushes go to `localhost:5001` by default (or whatever `deploy.registry.local_url` resolves to)
- Authentication uses your AGNT5 API key

### Remote Registry
- Remote pushes use `deploy.registry.remote_url` when defined; otherwise the CLI falls back to the default remote registry (`iarun-agnt5-cr.protoml.dev`)
- Credentials come from `config.yaml` or, if omitted, reuse your API key
- When both `--push` and `--push-remote` are enabled the CLI pushes to the local registry first, then mirrors the tag to the remote endpoint

<Callout type="warning">
You can opt out of pushing entirely with `--push=false`, but keep in mind that `agnt5 deploy` still expects to deploy the latest image tag.
</Callout>

## Workspace Validation and Deployment

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

### Workspace States

| State | Action |
| --- | --- |
| **No workspace** | CLI creates one automatically and waits (up to 10 minutes) 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 |

### Deployment Process

When the workspace is ready the CLI constructs a deployment payload with your image reference, replica count, and resource hints, then polls every five seconds (for up to five minutes) for the deployment to reach a `running`/`ready` status. Upon success it prints handy follow-up steps, including a `curl` example and a reminder to inspect logs via `agnt5 logs`.

## Complete Example Workflow

```bash
# 1. Check deployment plan
agnt5 deploy --prod --dry-run --replicas 3

# 2. Build and deploy to production
agnt5 deploy --prod --replicas 3 --cpu 1 --memory 1Gi --tags v1.2.0

# 3. Monitor deployment (see deployment visibility commands)
agnt5 list --environment production
agnt5 logs
```

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


**Programmatic equivalents**: the CLI calls Control Plane HTTP endpoints — see [API reference](/api-reference/create-contact.md) for the request shapes