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. The Dockerfile is automatically generated when you run videosdk agent init.

requirements.txt

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

Dockerfile

A Dockerfile is automatically created when you run videosdk agent init. 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. By default it pushes to VideoSDK Cloud, which needs no external registry account and no image pull secret. To push to your own registry instead, pass --server with -u/-p, or use an image name that already includes a registry host.

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 (switches to your own registry)	VideoSDK registry
--username	-u	Registry username for authentication	None
--password	-p	Registry password for authentication	None
--managed		Force push to the VideoSDK registry, even if the image name has a host	Auto-detected

Which registry is used?

The CLI pushes to VideoSDK Cloud when any of the following is true:

• You omit --server and the image name has no registry host (for example, my-agent:v1).
• The image name already targets the VideoSDK registry.
• You pass the --managed flag.

Otherwise it pushes to your own registry (Docker Hub, ECR, GCR, ACR, GHCR, and so on).

Push to VideoSDK Cloud (Default)

# Build with a plain image name
videosdk agent build --image my-agent:v1

# Push to VideoSDK Cloud (default)
videosdk agent push --image my-agent:v1

Your image is stored in VideoSDK Cloud and pulled automatically at deploy time, so you can deploy without an image pull secret.

See the VideoSDK Registry guide for the full workflow.

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 my-agent:v1

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

  Registry  vcr.videosdk.live
  Image     vcr.videosdk.live/<your-project>/my-agent:v1

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

[Docker push output...]

✓ Successfully pushed image: vcr.videosdk.live/<your-project>/my-agent:v1

Examples

# Push to the VideoSDK registry (default)
videosdk agent push --image my-agent:v1

# Push to Docker Hub with authentication
videosdk agent push --image myrepo/myagent:v1 --server docker.io -u username -p token

# 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
VideoSDK Registry	vcr.videosdk.live (default)
Docker Hub	docker.io
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)
• The VideoSDK registry is the default and needs no image pull secret at deploy time
• Replace myrepo with your actual Docker registry username when using your own registry
• For private external registries, you must provide authentication credentials (-u/-p)
• 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.