The Complete Production SOP: How to Deploy and Run containerd & nerdctl Docker-Compatible Management in Autonomous AI Agents

To enable your coding agent (Codex, Claude Code, Cursor, or Windsurf) to natively invoke nerdctl operations, mount the skill specification directly into the project's root agent configuration directory (`.agents/skills/containerd-nerdctl-cli`) or global runtime directory (`~/.claude/skills/` or `.cursor/rules/`). The agent runtime parses the YAML frontmatter triggers and registers specific containerd management workflows into its tool evaluation loop.

---
name: "containerd-nerdctl-cli"
description: "Manage containerd runtimes directly with full Docker CLI compatibility and containerd features."
metadata:
  author: "containerd"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "use nerdctl run"
  - "switch containerd namespace"
  - "enable estargz lazy pulling nerdctl"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: true
  net_access: true
---

Before issuing container execution commands, the agent must confirm the status of the containerd daemon and CNI network plugins. Running `nerdctl info` validates that BuildKit is detected, rootless or rootful containerd is operational, and default bridge networks exist. Storing local configurations in `.env.local` preserves agent parameters across sub-sessions.

namespace = "default"
snapshotter = "overlayfs"
cni_path = "/opt/cni/bin"
cni_netconfpath = "/etc/cni/net.d"
insecure_registry = false

Agent engines like Claude Code and Codex evaluate system-level prompt triggers against their skill registries. Formulating requests using target triggers such as 'switch containerd namespace' or 'enable estargz lazy pulling nerdctl' causes the runtime to lock into the exact commands and safety guidelines defined in the SOP.

#!/usr/bin/env bash
set -euo pipefail

# Verified agent execution pattern with lazy pulling
nerdctl run -d \
  --name test-python-service \
  --snapshotter=stargz \
  -p 8000:8000 \
  ghcr.io/stargz-containers/python:3.9-esgz \
  python -m http.server 8000

A deterministic agent must verify that the target container reached the running state, ports are mapped correctly, and container logs show no immediate crashes. The verification gate requires inspecting the container via `nerdctl inspect` and checking the return code.

#!/usr/bin/env bash
status=$(nerdctl inspect --format '{{.State.Status}}' test-python-service 2>/dev/null || echo "missing")
if [ "$status" != "running" ]; then
  echo "Container verification failed. Current status: $status" >&2
  nerdctl logs --tail 20 test-python-service
  exit 1
fi
echo "Container healthy and active."