Docker Management Skill for Hermes Agent

This skill puts the full Docker CLI at your fingertips through Hermes Agent. You ask for a container to run, an image to build, or a Compose stack to bring up, and the agent translates that into the right commands. It is for anyone who already works with Docker and wants to delegate the routine operations to an autonomous agent, whether you are debugging a crashing service, cleaning up disk space, or reviewing a Dockerfile.

What it does

The skill covers the everyday Docker operations that make up most of a developer's workflow. It can run, stop, restart, and remove containers; build, pull, push, and tag images; manage volumes and networks; and drive Docker Compose stacks. It also helps with troubleshooting: reading logs, inspecting containers, checking resource usage, and freeing up disk space. When you ask the agent to do something Docker-related, it first figures out which domain the request falls into, then picks the appropriate commands from its toolkit.

Before you start

You need Docker Engine installed and running on the machine where Hermes Agent operates. Your user account must be in the docker group, or you must be prepared to use sudo for every command. Docker Compose v2 is required for Compose workflows; it ships with modern Docker installations, so you likely already have it. The skill itself has no additional dependencies beyond Docker.

Run this quick check to confirm your environment is ready:

docker --version && docker compose version

If this fails, Docker is not installed, the daemon is not running, or your user lacks permission. Fix those before asking the agent to do anything.

Quick Reference

The skill keeps a compact cheat sheet for the most common tasks. This is what the agent reaches for first when you give a short, direct instruction.

Task	Command
Run container (background)	`docker run -d --name NAME IMAGE`
Stop + remove	`docker stop NAME && docker rm NAME`
View logs (follow)	`docker logs --tail 50 -f NAME`
Shell into container	`docker exec -it NAME /bin/sh`
List all containers	`docker ps -a`
Build image	`docker build -t TAG .`
Compose up	`docker compose up -d`
Compose down	`docker compose down`
Disk usage	`docker system df`
Cleanup dangling	`docker image prune && docker container prune`

Procedure

1. Identify the domain

The agent starts by classifying your request into one of six areas. This determines which command family it will use.

Container lifecycle → run, stop, start, restart, rm, pause/unpause
Container interaction → exec, cp, logs, inspect, stats
Image management → build, pull, push, tag, rmi, save/load
Docker Compose → up, down, ps, logs, exec, build, config
Volumes & networks → create, inspect, rm, prune, connect
Troubleshooting → log analysis, exit codes, resource issues

If your request spans multiple domains, the agent will handle them in sequence. For example, "deploy my app and check its logs" triggers Compose up, then a logs command.

2. Container operations

Run a new container:

The skill knows the common flags for running containers: -d for detached, -it for interactive with a TTY, --rm to auto-remove on exit, -p for port mapping (host:container), -e for environment variables, -v for volumes, --name to name the container, and --restart for restart policies. Here are the patterns it uses.

# Detached service with port mapping
docker run -d --name web -p 8080:80 nginx

# With environment variables
docker run -d -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=mydb --name db postgres:16

# With persistent data (named volume)
docker run -d -v pgdata:/var/lib/postgresql/data --name db postgres:16

# For development (bind mount source code)
docker run -d -v $(pwd)/src:/app/src -p 3000:3000 --name dev my-app

# Interactive debugging (auto-remove on exit)
docker run -it --rm ubuntu:22.04 /bin/bash

# With resource limits and restart policy
docker run -d --memory=512m --cpus=1.5 --restart=unless-stopped --name app my-app

Manage running containers:

Once containers are running, you will often need to list, stop, start, restart, or remove them. The skill uses these standard commands.

docker ps                        # running containers
docker ps -a                     # all (including stopped)
docker stop NAME                 # graceful stop
docker start NAME                # start stopped container
docker restart NAME              # stop + start
docker rm NAME                   # remove stopped container
docker rm -f NAME                # force remove running container
docker container prune           # remove ALL stopped containers

Interact with containers:

For debugging or inspection, the skill can open a shell, view environment variables, run commands as a specific user, follow logs, copy files in and out, and inspect container details.

docker exec -it NAME /bin/sh          # shell access (use /bin/bash if available)
docker exec NAME env                   # view environment variables
docker exec -u root NAME apt update    # run as specific user
docker logs --tail 100 -f NAME         # follow last 100 lines
docker logs --since 2h NAME            # logs from last 2 hours
docker cp NAME:/path/file ./local      # copy file from container
docker cp ./file NAME:/path/           # copy file to container
docker inspect NAME                    # full container details (JSON)
docker stats --no-stream               # resource usage snapshot
docker top NAME                        # running processes

3. Image management

Building, pulling, pushing, and cleaning up images is a core part of the skill. It covers the full lifecycle.

# Build
docker build -t my-app:latest .
docker build -t my-app:prod -f Dockerfile.prod .
docker build --no-cache -t my-app .              # clean rebuild
DOCKER_BUILDKIT=1 docker build -t my-app .       # faster with BuildKit

# Pull and push
docker pull node:20-alpine
docker login ghcr.io
docker tag my-app:latest registry/my-app:v1.0
docker push registry/my-app:v1.0

# Inspect
docker images                          # list local images
docker history IMAGE                   # see layers
docker inspect IMAGE                   # full details

# Cleanup
docker image prune                     # remove dangling (untagged) images
docker image prune -a                  # remove ALL unused images (careful!)
docker image prune -a --filter "until=168h"   # unused images older than 7 days

4. Docker Compose

For multi-service stacks, the skill uses Docker Compose v2. It can start and stop services, rebuild images, follow logs, run one-off commands, and validate the configuration.

# Start/stop
docker compose up -d                   # start all services detached
docker compose up -d --build           # rebuild images before starting
docker compose down                    # stop and remove containers
docker compose down -v                 # also remove volumes (DESTROYS DATA)

# Monitoring
docker compose ps                      # list services
docker compose logs -f api             # follow logs for specific service
docker compose logs --tail 50          # last 50 lines all services

# Interaction
docker compose exec api /bin/sh        # shell into running service
docker compose run --rm api npm test   # one-off command (new container)
docker compose restart api             # restart specific service

# Validation
docker compose config                  # validate and view resolved config

Minimal compose.yml example:

When you need a starting point for a Compose file, the skill can produce a minimal but functional example. Note the healthcheck on the database service and the depends_on condition that waits for it.

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      # Password comes from the POSTGRES_PASSWORD secret, not the URL
      - DATABASE_URL=postgres://mydb_user@db:5432/mydb
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mydb
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

5. Volumes and networks

Persistent data and container networking are handled with the standard Docker commands.

# Volumes
docker volume ls                       # list volumes
docker volume create mydata            # create named volume
docker volume inspect mydata           # details (mount point, etc.)
docker volume rm mydata                # remove (fails if in use)
docker volume prune                    # remove unused volumes

# Networks
docker network ls                      # list networks
docker network create mynet            # create bridge network
docker network inspect mynet           # details (connected containers)
docker network connect mynet NAME      # attach container to network
docker network disconnect mynet NAME   # detach container
docker network rm mynet                # remove network
docker network prune                   # remove unused networks

6. Disk usage and cleanup

Before cleaning anything, the skill always runs a diagnostic to see what is actually using space. Then it applies targeted cleanup, and only with your confirmation does it move to aggressive cleanup.

# Check what's using space
docker system df                       # summary
docker system df -v                    # detailed breakdown

# Targeted cleanup (safe)
docker container prune                 # stopped containers
docker image prune                     # dangling images
docker volume prune                    # unused volumes
docker network prune                   # unused networks

# Aggressive cleanup (confirm with user first!)
docker system prune                    # containers + images + networks
docker system prune -a                 # also unused images
docker system prune -a --volumes       # EVERYTHING — named volumes too

Warning: Never run docker system prune -a --volumes without confirming with the user. This removes named volumes with potentially important data.

Pitfalls

The skill includes a troubleshooting table for the most common Docker failures. When something goes wrong, the agent checks these patterns first.

Problem	Cause	Fix
Container exits immediately	Main process finished or crashed	Check `docker logs NAME`, try `docker run -it --entrypoint /bin/sh IMAGE`
"port is already allocated"	Another process using that port	`docker ps` or `lsof -i :PORT` to find it
"no space left on device"	Docker disk full	`docker system df` then targeted prune
Can't connect to container	App binds to 127.0.0.1 inside container	App must bind to `0.0.0.0`, check `-p` mapping
Permission denied on volume	UID/GID mismatch host vs container	Use `--user $(id -u):$(id -g)` or fix permissions
Compose services can't reach each other	Wrong network or service name	Services use service name as hostname, check `docker compose config`
Build cache not working	Layer order wrong in Dockerfile	Put rarely-changing layers first (deps before source code)
Image too large	No multi-stage build, no .dockerignore	Use multi-stage builds, add `.dockerignore`

Verification

After any Docker operation, the skill verifies the result. This is not optional; it is how you know the operation actually succeeded.

Container started? → docker ps (check status is "Up")
Logs clean? → docker logs --tail 20 NAME (no errors)
Port accessible? → curl -s http://localhost:PORT or docker port NAME
Image built? → docker images | grep TAG
Compose stack healthy? → docker compose ps (all services "running" or "healthy")
Disk freed? → docker system df (compare before/after)

Dockerfile Optimization Tips

When you ask the skill to review or create a Dockerfile, it suggests these improvements. They are general best practices that apply to most projects.

Multi-stage builds, separate build environment from runtime to reduce final image size
Layer ordering, put dependencies before source code so changes don't invalidate cached layers
Combine RUN commands, fewer layers, smaller image
Use .dockerignore, exclude node_modules, .git, __pycache__, etc.
Pin base image versions, node:20-alpine not node:latest
Run as non-root, add USER instruction for security
Use slim/alpine bases, python:3.12-slim not python:3.12

When not to use it

This skill is not a substitute for understanding Docker. If you need to design a complex networking topology, debug a kernel-level issue, or write a production-grade Dockerfile from scratch, you are better off doing that yourself. The skill is a fast and reliable operator for standard tasks, not a replacement for expertise.

Limits and gotchas

The skill inherits all the limitations of the Docker CLI. It cannot do anything Docker itself cannot do. It also requires that the Docker daemon is running and that the user has appropriate permissions. The most important gotcha is the destructive cleanup commands: docker compose down -v and docker system prune -a --volumes will delete data permanently. The skill will always ask for confirmation before running those, but you should still be careful about what you approve.

What pairs with this

This skill is part of the DevOps category in Hermes Agent's optional skills. It works well alongside other infrastructure skills, such as those for Kubernetes or cloud provisioning, when you need to manage containers as part of a larger deployment workflow. Check the Hermes Agent documentation for the full list of optional skills in the DevOps category.

Docker Management with Hermes Agent: Containers, Images, Compose