agentvisor build

Build an agent container image with embedded host runtime and guest sandbox.

Synopsis

agentvisor build <path> [options]

Description

The build command creates a combined container image containing:

Host runtime with gVisor
Guest rootfs with your agent code
Python dependencies installed
Configuration embedded

Arguments

Argument	Description
`<path>`	Path to agent directory containing agent.py

Options

Option	Default	Description
`--bundle-mcp-tools`	`false`	Bundle MCP tools rootfs into the combined image at /opt/agentvisor/mcp-tools-rootfs
`--cpu`	`1.0`	CPU limit for guest sandbox (e.g., 0.5, 1.0, 2.0)
`--from-guest-image`	-	Use pre-built guest OCI image instead of building from source
`--guest-image`	-	Guest base image (default auto-detected)
`--host-image`	-	Base host image (default: version-matched image)
`--interpreter`	-	Override detected interpreter (e.g., python3.12)
`--local-guest-rootfs`	-	Use local guest rootfs instead of building (dev mode)
`--local-host-rootfs`	-	Use local host rootfs instead of pulling image (dev mode)
`--mcp-tools-image`	-	MCP tools OCI image to bundle into combined image (default: version-matched image)
`--memory`	`512Mi`	Memory limit for guest sandbox (e.g., 512Mi, 1Gi)
`--no-cache`	`false`	Disable build cache
`--platform`	-	Target platform(s) for build (e.g., 'amd64', 'amd64,arm64', 'linux/amd64')
`--push`	`false`	Push to registry after build
`--registry-ca-data`	-	Base64-encoded PEM CA certificate to trust for registry operations (alternative to --registry-ca-file)
`--registry-ca-file`	-	Path to a PEM CA certificate to trust when pulling/pushing images from a private registry
`--registry-insecure`	`false`	Skip TLS certificate verification for registry operations; requires AGENTVISOR_TLS_ALLOW_INSECURE=true
`-t, --tag`	-	Name and tag for the combined image (required)

Examples

Basic Build

agentvisor build ./my-agent -t my-agent:v1

Build and Push

agentvisor build ./my-agent \
    -t registry.example.com/my-agent:v1 \
    --push

Custom Base Images

agentvisor build ./my-agent \
    -t my-agent:v1 \
    --host-image myregistry/agentvisor-host:dev \
    --guest-image myregistry/agentvisor-guest-python:dev

Single Platform Build

Build for a specific architecture (useful for cross-compilation):

# Short form (linux is implied)
agentvisor build ./my-agent \
    -t my-agent:v1 \
    --platform amd64

# OCI format also accepted
agentvisor build ./my-agent \
    -t my-agent:v1 \
    --platform linux/arm64

Multi-Platform Build

Build for multiple architectures and publish as an OCI manifest list:

agentvisor build ./my-agent \
    -t registry.example.com/my-agent:v1 \
    --platform amd64,arm64 \
    --push

Multi-arch requires --push

Multi-architecture images are stored as OCI manifest lists (also called "fat manifests"), which can only be stored in container registries. When building for multiple platforms, you must use --push to publish the manifest list to a registry.

Without --push, multi-arch builds will only save the host architecture image to the local Docker daemon.

Agent Directory Structure

The build command expects:

my-agent/
├── agent.py              # LangGraph agent code
├── langgraph.json        # Optional: graph configuration (falls back to auto-detection if absent)
├── requirements.txt      # Optional: Python dependencies
├── .dockerignore         # Optional: files to exclude
└── ...                   # Other source files

.dockerignore

Place a .dockerignore file in your agent directory to exclude files from the guest image. This is useful for keeping policy files, documentation, and test data out of the sandbox.

policies/
README.md
**/*.log

Patterns are merged with built-in defaults (.git/, __pycache__/, .venv/, .env, etc.). See Container Layout — Ignore Patterns for the full syntax reference.

Custom Dockerfile

Place a Dockerfile in the agent directory to override the embedded build template. This is the primary way to install extra system packages, language runtimes, or tools into the guest image:

FROM {{.Image}}

# The agentvisor-guest base image is built on ubi9/ubi-minimal — use microdnf, not apt-get.
# Note: the default `python` image variant has microdnf removed as a hardening step.
# OS-package installation in custom Dockerfiles requires the `minimal` variant
# (typical for exec/interactive use cases). LangGraph agents using the python variant
# should install additional dependencies via pip/requirements.txt instead.
RUN microdnf install -y git && microdnf clean all

{{if .HasRequirements -}}
COPY agent/requirements.txt /tmp/requirements.txt
RUN pip install --no-cache-dir -r /tmp/requirements.txt
{{end -}}
COPY agent /app/agent

The file is processed as a Go text/template with these variables:

Variable	Description
`{{.Image}}`	Full versioned base image reference
`{{.ImageRepo}}`	Repository without tag
`{{.ImageVersion}}`	Version portion of the tag
`{{.ImageVariant}}`	`python` or `minimal`
`{{.HasRequirements}}`	`true` if `requirements.txt` exists

The same mechanism applies to agentvisor exec — the same Dockerfile is used for both local interactive sessions and production builds. See exec — Customizing the Sandbox Environment.

Configuration

Agent configuration uses the standard langgraph.json format:

{
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "python_version": "3.12",
  "dependencies": ["requests", "httpx"]
}

Build Process

Load host image: Pull or use local host base image
Extract guest rootfs: Extract filesystem from guest base image
Install dependencies: Run pip install -r requirements.txt
Copy source: Copy agent files to /app/
Create image: Add guest rootfs as layer at /opt/guest-rootfs
Bundle MCP tools (when --bundle-mcp-tools is set): Extracts the mcp-tools rootfs and adds it as a layer at /opt/agentvisor/mcp-tools-rootfs
Tag and push: Apply tag and optionally push

MCP Tools

When your agent uses stdio MCP servers, AgentVisor needs a mcp-tools rootfs (containing node/npx and python/uvx) to sandbox each server. By default this is pulled on first use at runtime. The --bundle-mcp-tools flag bakes it into the combined image at build time, eliminating the runtime pull.

# Build with bundled mcp-tools rootfs (no network needed at runtime for the sandbox image)
agentvisor build ./my-mcp-agent \
    -t registry.example.com/my-agent:v1 \
    --bundle-mcp-tools \
    --push

The --mcp-tools-image flag specifies which OCI image to extract the rootfs from (defaults to the version-matched ghcr.io/manetu/agentvisor/agentvisor-mcp-tools:<version>):

agentvisor build ./my-mcp-agent \
    -t my-agent:v1 \
    --bundle-mcp-tools \
    --mcp-tools-image ghcr.io/myorg/custom-mcp-tools:latest

To pre-install specific npm or PyPI packages into the bundled rootfs, declare them in mav-agent-config.yaml:

# mav-agent-config.yaml
mcp:
  prepull:
    - manager: npm
      package: "@modelcontextprotocol/server-filesystem"
    - manager: pypi
      package: mcp-server-fetch

See MCP Gateway: Pre-installing Packages (prepull) for the full schema.

Multi-Architecture Builds

AgentVisor supports building images for multiple CPU architectures (amd64 and arm64) to support heterogeneous deployment environments.

Platform Formats

The --platform flag accepts several formats:

Format	Example	Description
Short form	`amd64`	Architecture only (linux is implied)
OCI format	`linux/amd64`	Full OS/architecture specification
Multiple	`amd64,arm64`	Comma-separated list
Architecture aliases	`x86_64`, `aarch64`	Automatically normalized

How It Works

When --platform is specified:

Platform validation: The build verifies that base images are available for the requested platform(s)
Platform-specific builds: Each platform is built separately with the correct native binaries
Manifest list creation: For multi-arch builds, images are combined into an OCI Image Index

For cross-platform builds (e.g., building amd64 on an arm64 host), Docker buildx with QEMU emulation is used to run pip install for the target architecture, ensuring native Python wheels are installed correctly.