Get the FREE Ultimate OpenClaw Setup Guide →

nerdctl

npx machina-cli add skill typhoonzero/awesome-acp-skills/nerdctl --openclaw
Files (1)
SKILL.md
5.2 KB

nerdctl CLI

This skill covers the usage of nerdctl, a Docker-compatible command-line interface for containerd. nerdctl provides a user experience similar to docker but interacts directly with containerd.

Overview

nerdctl supports most Docker commands and adds some containerd-specific features.

  • :whale: indicates Docker compatibility.
  • :nerd_face: indicates nerdctl-specific features.

Container Management

Running Containers

Command: nerdctl run [OPTIONS] IMAGE [COMMAND] [ARG...]

  • Common Flags:
    • -d, --detach: Run in background.
    • -i, --interactive: Keep STDIN open.
    • -t, --tty: Allocate a pseudo-TTY.
    • --rm: Automatically remove the container when it exits.
    • --name: Assign a name to the container.
    • -p, --publish: Publish a container's port(s) to the host (e.g., -p 8080:80).
    • -v, --volume: Bind mount a volume (e.g., -v /host:/container).
    • --net, --network: Connect to a network (bridge, host, none, CNI).
    • -e, --env: Set environment variables.
    • --restart: Restart policy (no, always, on-failure, unless-stopped).
    • --platform: Set platform (e.g., amd64, arm64).

Listing Containers

Command: nerdctl ps [OPTIONS]

  • Flags:
    • -a, --all: Show all containers (default shows just running).
    • -q: Only display IDs.

Executing Commands

Command: nerdctl exec [OPTIONS] CONTAINER COMMAND [ARG...]

  • Flags:
    • -i, -t, -d, -w (workdir), -e (env), --privileged, -u (user).

Lifecycle Management

  • Start: nerdctl start [OPTIONS] CONTAINER
  • Stop: nerdctl stop [OPTIONS] CONTAINER
  • Restart: nerdctl restart [OPTIONS] CONTAINER
  • Kill: nerdctl kill [OPTIONS] CONTAINER
  • Pause/Unpause: nerdctl pause CONTAINER / nerdctl unpause CONTAINER
  • Remove: nerdctl rm [OPTIONS] CONTAINER
    • -f, --force: Force removal of running containers.
    • -v: Remove anonymous volumes.

Inspection & Logs

  • Logs: nerdctl logs [OPTIONS] CONTAINER
    • -f: Follow log output.
    • --since, --until: Filter by time.
    • -n, --tail: Show last N lines.
  • Inspect: nerdctl inspect CONTAINER
    • Returns detailed JSON information about the container.
  • Port: nerdctl port CONTAINER
  • Stats: nerdctl stats

Image Management

Listing Images

Command: nerdctl images [OPTIONS]

  • -a: Show all images.

Pulling & Pushing

  • Pull: nerdctl pull [OPTIONS] NAME[:TAG]
    • --platform: Pull for specific platform (can be specified multiple times).
    • --all-platforms: Pull all platforms.
    • --unpack: Unpack image (auto/true/false).
  • Push: nerdctl push [OPTIONS] NAME[:TAG]
    • --platform, --all-platforms.
    • --sign: Sign image (cosign/notation).

Building Images

Command: nerdctl build [OPTIONS] PATH

  • -t, --tag: Name and tag.
  • -f, --file: Dockerfile path.
  • --target: Build stage target.
  • --build-arg: Build-time variables.
  • --no-cache: Disable cache.
  • --platform: Set target platform.
  • --output: Output destination (local, oci, docker, tar, image).

Other Image Operations

  • Tag: nerdctl tag SOURCE TARGET
  • Remove: nerdctl rmi [OPTIONS] IMAGE
  • Load: nerdctl load -i <tarball>
  • Save: nerdctl save -o <tarball> IMAGE
  • History: nerdctl history IMAGE
  • Prune: nerdctl image prune

Network Management

  • List: nerdctl network ls
  • Create: nerdctl network create [OPTIONS] NETWORK
  • Inspect: nerdctl network inspect NETWORK
  • Remove: nerdctl network rm NETWORK
  • Prune: nerdctl network prune

Volume Management

  • List: nerdctl volume ls
  • Create: nerdctl volume create [OPTIONS] VOLUME
  • Inspect: nerdctl volume inspect VOLUME
  • Remove: nerdctl volume rm VOLUME
  • Prune: nerdctl volume prune

Namespace Management (:nerd_face:)

nerdctl natively supports containerd namespaces.

  • List: nerdctl namespace ls
  • Create: nerdctl namespace create NAME
  • Inspect: nerdctl namespace inspect NAME
  • Remove: nerdctl namespace remove NAME
  • Update: nerdctl namespace update NAME

Compose

nerdctl supports docker-compose style orchestration.

Command: nerdctl compose [OPTIONS] COMMAND

  • Commands: up, down, ps, logs, build, pull, push, restart, start, stop, run, exec, config.
  • Note: Standard docker-compose.yml files are supported.

System & Advanced

  • Info: nerdctl info
  • Version: nerdctl version
  • Prune System: nerdctl system prune
  • Events: nerdctl events
  • Login/Logout: nerdctl login, nerdctl logout
  • IPFS: nerdctl supports IPFS for pulling/pushing images (ipfs:// prefix).

Common Tasks Reference

Run a web server

nerdctl run -d -p 8080:80 --name my-nginx nginx:alpine

Build an image

nerdctl build -t my-app:v1 .

Clean up unused resources

nerdctl system prune -a

Explore container process

nerdctl exec -it my-container /bin/sh

Source

git clone https://github.com/typhoonzero/awesome-acp-skills/blob/master/nerdctl/SKILL.mdView on GitHub

Overview

nerdctl is a Docker-compatible command-line interface for containerd. It lets you manage containers, images, volumes, and networks with a familiar docker-like experience while operating directly against containerd.

How This Skill Works

nerdctl translates Docker-style commands into containerd API calls and runtime operations. It supports common workflows for running, listing, inspecting, and removing containers, as well as image management (pull/build/push), and network/volume handling, exposing containerd-specific features when needed.

When to Use It

  • When you manage containers directly on a containerd-backed host and want a Docker-like CLI.
  • When you run services with port mappings (-p) and bind mounts (-v) to persist data and expose ports.
  • When pulling, building, or pushing images, including multi-platform images with --platform and --all-platforms.
  • When you need quick debugging with logs (-f) and container inspection (-i/-e/-p).
  • When configuring networks and volumes using nerdctl network and nerdctl volume commands.

Quick Start

  1. Step 1: Install nerdctl and verify containerd is running (nerdctl --version; systemctl status containerd).
  2. Step 2: Run a simple container to verify (nerdctl run -d --name hello -p 8080:80 nginx:latest).
  3. Step 3: Inspect and manage (nerdctl ps -a; nerdctl logs -f hello; nerdctl stop hello; nerdctl rm hello).

Best Practices

  • Use --rm for ephemeral runs to keep the host clean.
  • Combine -d with --name and -p/-v to run long-lived services cleanly.
  • Use -q for scripting to capture container IDs without extra output.
  • Specify --platform for cross-arch workloads and use --all-platforms when pulling multi-arch images.
  • Regularly prune unused images and networks with nerdctl image prune and nerdctl network prune.

Example Use Cases

  • nerdctl run -d --name web -p 8080:80 nginx:latest
  • nerdctl run -d -v data:/var/lib/mysql --name db mysql:5.7
  • nerdctl ps -a
  • nerdctl pull --platform linux/arm64 nginx:latest
  • nerdctl build -t myapp:latest -f Dockerfile .

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗