Build & Push

After developing your AI agent, you need to package it as a Docker image and push it to a container registry before deploying to Agent Cloud. This section covers the build and push commands.

Prerequisites

Before building your image, you must have a Dockerfile and a requirements.txt file in your project's root directory.

requirements.txt

Create a requirements.txt file listing all the Python packages your agent needs.

Dockerfile

Create a Dockerfile with the necessary configuration for your agent. Below is a minimal multi-stage build example that keeps your final image small while ensuring all build-time dependencies are met.

# Stage 1: Build Stage
FROM python:3.12-slim AS builder

WORKDIR /app

# Install build-time dependencies
# These are only needed to compile/build packages like aec-audio-processing
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    python3-dev \
    swig \
    pkg-config \
    meson \
    ninja-build \
    && rm -rf /var/lib/apt/lists/*

# Create a virtual environment to keep dependency installation isolated and easy to move
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt


# Stage 2: Runtime Stage
FROM python:3.12-slim

WORKDIR /app

# Copy the virtual environment from the builder stage
# This includes all the installed Python packages but NONE of the build tools
COPY --from=builder /opt/venv /opt/venv

# Ensure the app uses the virtual environment's Python and packages
ENV PATH="/opt/venv/bin:$PATH"

# Install minimal runtime libraries if needed (e.g., libstdc++ for compiled extensions)
RUN apt-get update && apt-get install -y --no-install-recommends \
    libstdc++6 \
    && rm -rf /var/lib/apt/lists/*

# Copy your application code
COPY agent.py .

# Run the application
CMD ["python", "agent.py"]

Build

The build command creates a Docker image for your agent using a Dockerfile.

Usage

videosdk agent build [OPTIONS]

Options

Option	Short	Description	Default
--image	-i	Image name with optional tag (e.g., myrepo/myagent:v1)	From videosdk.yaml
--file	-f	Path to Dockerfile	./Dockerfile

What Happens

1. Dockerfile Detection: The CLI locates your Dockerfile (default: ./Dockerfile)
2. Image Build: Docker builds the image for the linux/arm64 platform
3. Local Storage: The built image is stored in your local Docker registry

Example Output

$ videosdk agent build --image myrepo/myagent:v1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Building Docker Image
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Platform    linux/arm64
  Image       myrepo/myagent:v1
  Dockerfile  /path/to/your/project/Dockerfile

────────────────────────────────────────

[Docker build output...]

✓ Successfully built image: myrepo/myagent:v1

Examples

# Build with explicit image name
videosdk agent build --image myrepo/myagent:v1

# Build with custom Dockerfile
videosdk agent build --image myrepo/myagent:v1 --file Dockerfile.prod

# Build using image from videosdk.yaml
videosdk agent build

Notes

• The image name must be lowercase
• In examples like myrepo/myagent:v1, myrepo is a placeholder for your Docker registry username (e.g., your Docker Hub username).
• If --image is not provided, the CLI reads from agent.image in your videosdk.yaml
• Docker must be installed and running on your machine
• The build uses linux/arm64 platform for Agent Cloud compatibility

Push

The push command uploads your Docker image to a container registry.

Usage

videosdk agent push [OPTIONS]

Options

Option	Short	Description	Default
--image	-i	Image name with tag (e.g., myrepo/myagent:v1)	From videosdk.yaml
--server	-s	Registry server URL	docker.io
--username	-u	Registry username for authentication	None
--password	-p	Registry password for authentication	None

What Happens

1. Authentication (optional): If credentials are provided, the CLI logs into the registry
2. Image Push: The Docker image is uploaded to the specified registry
3. Ready for Deploy: The image is now available for Agent Cloud deployments

Example Output

$ videosdk agent push --image myrepo/myagent:v1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Pushing Docker Image
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Image     myrepo/myagent:v1
  Registry  docker.io

────────────────────────────────────────

[Docker push output...]

✓ Successfully pushed image: myrepo/myagent:v1

Examples

# Push to Docker Hub (default)
videosdk agent push --image myrepo/myagent:v1

# Push to GitHub Container Registry with authentication
videosdk agent push --image myrepo/myagent:v1 --server ghcr.io -u username -p token

# Push to private registry
videosdk agent push --image myrepo/myagent:v1 --server registry.example.com -u user -p pass

# Push using image from videosdk.yaml
videosdk agent push

Supported Registries

Registry	Server URL
Docker Hub	docker.io (default)
GitHub Container Registry	ghcr.io
AWS ECR	<account>.dkr.ecr.<region>.amazonaws.com
Google Container Registry	gcr.io
Azure Container Registry	<registry>.azurecr.io

Notes

• Ensure the image is built before pushing (videosdk agent build)
• Replace myrepo with your actual Docker registry username.
• For Docker Hub, you can omit --server as it's the default
• For private registries, you must provide authentication credentials
• The registry server is automatically detected from the image name if --server is not specified

yaml Configuration

Both commands can read the image name from your videosdk.yaml configuration file:

agent:
  id: your-agent-id
  image: myrepo/myagent:v1

When the image is configured in videosdk.yaml, you can simply run:

videosdk agent build
videosdk agent push

Example

Here's a typical workflow for building and pushing your agent:

# 1. Build the Docker image
videosdk agent build --image myrepo/myagent:v1

# 2. Push to container registry
videosdk agent push --image myrepo/myagent:v1

# 3. Deploy to Agent Cloud (covered in deployment docs)
videosdk agent deploy --image myrepo/myagent:v1

Next Steps

After pushing your image to a container registry, you're ready to deploy your agent to Agent Cloud. See the deployment documentation for more details.