Docs
⌘ K
API Reference Deployment Commands — AGNT5 CLI

Deployment Commands

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.

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

The complete deployment workflow with build, push, and deployment orchestration.

Syntax 

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

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
Note:

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).

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
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.

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

# 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
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.

© 2026 AGNT5
llms.txt