# Chainguard Guardener Dockerfile Migration

URL: https://edu.chainguard.dev/chainguard/guardener/dockerfile-migration.md
Last Modified: July 13, 2026
Tags: GitHub, AI, Chainguard Containers

Use Chainguard Guardener to migrate, optimize, upgrade, and validate your Dockerfiles against Chainguard Containers with AI-driven, iterative conversion.

The Dockerfile migration feature converts your Dockerfiles to use Chainguard Containers. It uses AI to iteratively translate instructions, build images, compare results, and fix issues until the migrated Dockerfile works as expected.
Unlike the Guardener’s Actions Security and Commit Verification features, Dockerfile migration does not run through the GitHub App or the .chainguard/ configuration directory. Instead, you drive it locally through chainctl agent dockerfile commands. The AI runs server-side and scans your workspace to perform its analysis, while Docker builds and file access remain local to your machine.
Note: The Guardener is in beta.
This page is a reference for the chainctl agent dockerfile commands. For a full walkthrough — including prerequisites, a step-by-step migration, available optimizers, a before-and-after example, and FAQ — see the Dockerfile migration guide.
How it works The migration agent runs on Chainguard’s servers, but it never touches your machine directly. Every file read, Docker build, and command is requested by the agent and mediated by chainctl on your machine. The local client evaluates each request, and only performs and returns the ones it deems acceptable — so you stay in control of what the agent can do and what data is sent back.
Your machine (client) Chainguard (server) ┌───────────────────────────┐ ┌──────────────────────┐ │ chainctl │◀── request ───│ Migration agent │ │ │ read a file, │ (AI) │ │ Dockerfile │ run a build, │ │ │ build context │ run a command│ │ │ Docker │ │ │ │ ▼ │ │ │ │ evaluate request: │ │ │ │ allowed? │ │ │ │ ▼ │─── result ───▶│ analyzes result, │ │ perform locally, │ (only for │ plans next step │ │ return result │ approved │ │ │ │ requests) │ │ └───────────────────────────┘ └──────────────────────┘Because every action is mediated by the local client, the agent can’t read a file, run a build, or execute a command unless chainctl approves the request first.
IAM access Access to Dockerfile migration is governed by Chainguard IAM roles:
Action Minimum role Accepting the Guardener legal terms for your organization (required once before anyone can run sessions) guardener.admin or owner Running Dockerfile migration sessions guardener.user See the Built-in Roles and Capabilities Reference for details.
Commands chainctl agent dockerfile includes the following subcommands:
Command What it does build Migrate a Dockerfile to a Chainguard equivalent image optimize Optimize an already-migrated Dockerfile upgrade Upgrade package versions in a Dockerfile validate Validate a migrated Dockerfile To run a basic migration, provide the path to your Dockerfile and a target image tag:
chainctl agent dockerfile build -f Dockerfile \ -t myapp:chainguardFor CI environments or automated workflows, use the --non-interactive flag to skip prompts and automatically select the first suggestion:
chainctl agent dockerfile build -f Dockerfile \ --non-interactiveTo optimize an already-migrated Dockerfile, run the optimize subcommand. Pass a comma-separated list to --optimizers to run only specific optimizers:
chainctl agent dockerfile optimize -f Dockerfile \ --optimizers=cache,securityTo upgrade outdated packages in a Dockerfile without modifying any files, combine upgrade with --dry-run:
chainctl agent dockerfile upgrade -f Dockerfile \ --dry-runFor the complete set of usage examples, see Usage examples in the migration guide.
Agent access The Dockerfile migration agent runs server-side, but its access to your environment is scoped to what it needs to analyze and migrate a single Dockerfile:
Workspace analysis. The agent scans your workspace to understand your Dockerfile and build context. Analysis tools. During a migration, the agent has access to tools for: Searching APKINDEX. Finding which package provides a given binary or library. Comparing installed packages and filesystem layers between the original and migrated images. Running commands in built images. Reading build context files such as requirements.txt, package.json, and similar. Interactive guidance. If the agent cannot resolve an issue automatically, it prompts you for guidance with suggested alternatives. In --non-interactive mode it skips these prompts and automatically selects the first suggestion. Next steps Dockerfile migration guide — Full walkthrough, prerequisites, optimizers, and FAQ. Actions Security — Recommend and migrate GitHub Actions to hardened, SHA-pinned equivalents. Commit Verification — Require cryptographically signed commits in pull requests.