The Complete Production SOP: How to Deploy and Run containerd CRI Socket Troubleshooting & crictl in Autonomous AI Agents
Step-by-step SOP to install and run containerd CRI Socket Troubleshooting & crictl in Codex, Claude Code, and Cursor. Includes verified prompts and debug steps.
Technical Overview & Architectural Context
Autonomous coding agents like Codex, Claude Code, and Cursor frequently fail when debugging Kubernetes node runtime failures because they default to standard docker CLI commands or high-level kubectl calls that do not expose low-level container runtime interface (CRI) anomalies. In bare-metal or managed Kubernetes (EKS/GKE) worker nodes running containerd without Docker engine, an agent attempting `docker ps` will immediately halt with socket errors, while `kubectl describe pod` often masks low-level sandbox creation stalls, cgroup driver mismatches, or hanging unix domain sockets at `/run/containerd/containerd.sock`. The `containerd-cri-socket-troubleshoot` skill equips autonomous agents with deterministic standard operating procedures specifically tailored to `crictl`. Instead of hallucinating missing Docker daemons or running invasive node restarts, the agent deterministically inspects endpoint configurations in `/etc/crictl.yaml`, queries pod sandboxes directly with `crictl pods`, isolates stuck tasks via `crictl inspectp`, and extracts raw container stderr streams from the node filesystem. This establishes deterministic diagnostics while guarding against unprivileged sandbox execution and context window exhaustion.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into the agent runtime path.
Autonomous agents discover domain skills by scanning dedicated skill directories (e.g., `~/.claude/skills`, `.cursor/rules`, or workspace `.codex/skills`). We pull the canonical SKILL.md from aSkills.dev and place it in the agent's target runtime directory so the trigger hooks ('troubleshoot containerd crictl', 'inspect pod sandboxes crictl', 'debug container crashloop crictl') are automatically registered in the system prompt.
mkdir -p ~/.agents/skills/containerd-cri-socket-troubleshoot && curl -fsSL https://askills.dev/api/skills/containerd-cri-socket-troubleshoot/raw -o ~/.agents/skills/containerd-cri-socket-troubleshoot/SKILL.md---
name: "containerd-cri-socket-troubleshoot"
description: "Diagnose pod startup failures, container crashes, and runtime socket stalls using crictl."
metadata:
author: "containerd"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "troubleshoot containerd crictl"
- "inspect pod sandboxes crictl"
- "debug container crashloop crictl"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# containerd CRI Socket Troubleshooting & crictl
Troubleshoots Kubernetes node runtimes with crictl: inspecting pod sandboxes (crictl pods), analyzing container logs and events, querying CRI socket health (/run/containerd/containerd.sock), and clearing stuck containers.
## When to Invoke
Invoke this skill whenever you need to:
- troubleshoot containerd crictl
- inspect pod sandboxes crictl
- debug container crashloop crictl
## Execution SOP & Rules
1. Configure crictl endpoint in /etc/crictl.yaml: runtime-endpoint: unix:///run/containerd/containerd.sock.
2. List pod sandboxes: crictl pods --name <pod_name> and check status: crictl inspectp <pod_id>.
3. Fetch container logs directly: crictl logs <container_id>.
4. Force stop and remove stuck containers: crictl stop <id> && crictl rm <id>.
## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.Symlink this skill into workspace-level `.cursor/rules/containerd.md` or `.claude/skills/` to restrict rule injection only to node-level maintenance repositories, avoiding token overhead in app codebases.
Ensure the containing directory has read permissions for the agent subshell user; non-root agents running in restricted sandbox containers may fail to parse files under root-owned paths.
CRI Socket & Configuration Validation
Verify crictl configuration points deterministically to the active containerd domain socket.
By default, `crictl` attempts to connect to multiple historical CRI endpoints if `/etc/crictl.yaml` is absent, causing latency warnings and eventual timeout failures. In this step, ensure `/etc/crictl.yaml` specifies `unix:///run/containerd/containerd.sock` and verify socket accessibility.
sudo mkdir -p /etc && sudo tee /etc/crictl.yaml > /dev/null <<EOF
runtime-endpoint: unix:///run/containerd/containerd.sock
image-endpoint: unix:///run/containerd/containerd.sock
timeout: 10
debug: false
EOF
sudo crictl info > /dev/null && echo 'CRI Socket Connected Successfully'runtime-endpoint: unix:///run/containerd/containerd.sock
image-endpoint: unix:///run/containerd/containerd.sock
timeout: 10
debug: falseInstruct your agent to check `test -S /run/containerd/containerd.sock` before executing crictl queries to detect dead or unresponsive runtime daemons without stalling command buffers.
On Debian/Ubuntu and systemd-based hosts, containerd might expose its socket at `/run/containerd/containerd.sock`, but K3s or microk8s use custom paths like `/run/k3s/containerd/containerd.sock`.
Intent Matching & Trigger Invocation
Invoke the autonomous agent with explicit triggers to initiate crictl pod sandbox analysis.
Provide a high-fidelity prompt incorporating the registered triggers (`troubleshoot containerd crictl`, `inspect pod sandboxes crictl`, `debug container crashloop crictl`). The runtime parses the request, activates the SOP steps, and queries the container sandbox state machine without deviating into unsupported Docker commands.
claude 'A pod named payment-processor is stuck in CrashLoopBackOff on this node. Please troubleshoot containerd crictl and inspect pod sandboxes crictl to identify why the container exits.'Specify the target pod name in the trigger prompt to enable the agent to immediately execute `crictl pods --name <target>` rather than listing hundreds of cluster-wide sandboxes.
Avoid vague commands like 'check docker logs'; this can trigger fallback behavior where the agent searches for docker binaries instead of activating the crictl skill.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks before accepting agent deliverables.
After diagnosing or restarting containers via crictl, the agent must execute validation commands confirming the pod sandbox transitioned to the `Ready` state or correctly recorded exit codes in the audit report.
crictl pods --name payment-processor -s Ready && crictl ps --name payment-processor -s RunningRequire the agent to pipe `crictl inspect` output through jq filters (`jq .status.state`) to minimize output token consumption during validation steps.
Removing a stuck pod sandbox with `crictl rmp -f` without notifying kubelet will trigger an automatic kubelet recreation loop; always check node kubelet service logs alongside crictl actions.
Real-World Scenario: Triage CrashLoopBackOff Pod on Kubernetes Node Using crictl
“We have an order-api container crashing on worker-node-04. The kubelet logs show runtime errors. Please debug container crashloop crictl, inspect pod sandboxes crictl, identify the root cause, and provide a remediation report.”
Runtime Troubleshooting & Failure Modes
Root Cause: crictl is defaulting to deprecated dockershim socket paths because /etc/crictl.yaml is missing or contains unset runtime endpoints.
sudo tee /etc/crictl.yaml <<EOF
runtime-endpoint: unix:///run/containerd/containerd.sock
image-endpoint: unix:///run/containerd/containerd.sock
EOF
crictl infoRoot Cause: The user executing the AI agent process does not have write access to the containerd unix domain socket, which is typically owned by root:root with 0660 permissions.
sudo usermod -aG containerd $USER && sudo chmod 660 /run/containerd/containerd.sockFrequently Asked Questions (containerd CRI Socket Troubleshooting & crictl SOP)
Q:Can I use containerd CRI Socket Troubleshooting & crictl across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. It relies on standard POSIX commands (`crictl`), YAML configuration, and generic agent trigger parsing supported across Codex, Claude Code, Cursor, and Windsurf.
Q:How does containerd CRI Socket Troubleshooting & crictl prevent context window overflow during long agent sessions?
The skill instructs the agent to query pod sandboxes and container IDs selectively using filters (`--name`, `--pod`, `-s Running`) and view targeted logs (`crictl logs --tail 50 <id>`) rather than dumping full container inspect JSON structures or entire journalctl traces into the LLM context.
Q:Does this skill require escalated root or container permissions?
The skill specification itself has a 98/100 security score with `net_access: false` and `fs_write: workspace`. However, querying `/run/containerd/containerd.sock` on Linux worker nodes requires the host user running the agent subshell to possess root privileges or membership in the container runtime group.
Ready to equip your autonomous agent with containerd CRI Socket Troubleshooting & crictl?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.