container-host-aiops

Use this skill whenever the user needs to operate a single container host through the Docker Engine API, Portainer, or Podman — a one-shot host overview; container reads (list/inspect, logs tail, CPU/memory stats, top processes, restart summary); image reads (list, inspect with history, dangling, disk usage); volume reads (list, inspect, dangling); network reads (list, inspect); system reads (info, version, df disk-usage, recent events); Portainer stacks + endpoints; Compose-project rollups (list_compose_stacks, docker+podman); Podman pods (list_pods, podman-only); three flagship analyses — restart-loop RCA (crash-looping containers + cause/action), resource-pressure analysis (CPU/memory vs limits), and image & volume bloat (prune candidates + reclaimable bytes); and eight guarded writes (restart/stop/start/remove a container, prune images/volumes, update resource limits, recreate a Portainer stack). Always use this skill for "Docker host overview", "which containers are crash-looping", "restart loop", "why does this container keep restarting", "container CPU/memory usage", "docker logs", "which containers are near their limits", "resource pressure", "dangling images/volumes", "reclaim disk", "prune images", "stop/start/restart a container", "update a container's memory limit", "Portainer stacks", "compose stacks", "Podman pods" when the context is a Docker, Portainer, or Podman container host. Do NOT use when the target is a cluster orchestrator, a hypervisor, a storage appliance, a backup product, network device config, or OT/industrial equipment — route those to the appropriate other AIops-tools skill. This is for NON-orchestrator container hosts. Governed Docker/Portainer/Podman container-host operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Exercised against a live Docker Engine 27.5.1 daemon (doctor, overview, the three flagship analyses, and a governed stop_container with audit + undo recorded); the Portainer and Podman API paths are covered by the mock suite only. See docs/VERIFICATION.md.

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by Docker, Inc., Portainer.io, or any container-platform vendor. Product and trademark names belong to their owners. Source at github.com/AIops-tools/Container-Host-AIops under the MIT license.

Governed Docker + Portainer + Podman container-host operations — 38 MCP tools, every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.container-host-aiops/ (MCP + CLI alike), a runaway/budget safety guard, and undo-token recording. It records every operation; whether a write is permitted is the agent's or the account's call, not the skill's. A Docker target speaks the Docker Engine API over a unix socket or TCP; a Portainer target speaks the Portainer API (and proxies Docker); a Podman target speaks over its rootful/rootless socket (Docker-compat + libpod). The Portainer API token is stored encrypted (~/.container-host-aiops/secrets.enc, Fernet + scrypt) — never plaintext on disk; a local Docker/Podman socket needs no secret.

Standalone: the governance harness is bundled in the package (container_host_aiops.governance) — container-host-aiops has no external skill-family dependency. Verification: Exercised against a live Docker Engine 27.5.1 daemon (doctor, overview, the three flagship analyses, and a governed stop_container with audit + undo recorded); the Portainer and Podman API paths are covered by the mock suite only. See docs/VERIFICATION.md.

What This Skill Does

Domain	Tools	Count	Read or Write
Overview	one-shot host health	1	1 read
Containers	list/inspect, logs, stats, top, restart summary	6	6 read
Images	list, inspect (+history), dangling, disk usage	4	4 read
Volumes	list, inspect, dangling	3	3 read
Networks	list, inspect	2	2 read
System	info, version, df, events	4	4 read
Stacks	endpoints, stacks, stack detail (Portainer), compose-stack rollup (docker+podman)	4	4 read
Pods (Podman)	list pods (libpod)	1	1 read
Analyses (flagship)	restart-loop RCA, resource pressure, image/volume bloat	3	3 read
Writes	remove container, prune images, prune volumes, recreate stack	4	4 write (high)
	restart, stop, start, update container	4	4 write (medium)

The three analyses accept injected data for offline analysis, or pull live from a configured target. Portainer endpoints/stacks require a portainer target; list_compose_stacks works on docker or podman; list_pods requires a podman target.

Quick Install

bash

uv tool install container-host-aiops
container-host-aiops init       # interactive wizard: Docker/Podman socket or Portainer target
container-host-aiops doctor

When to Use This Skill

• Triage a host (overview): version + container state rollup + disk headline
• Find crash-looping containers (analyze restart-loop / restart_loop_rca): ranked by restart count with a likely cause and action from the exit code, plus a log tail
• Spot resource pressure (analyze resource-pressure / resource_pressure_analysis): CPU%/mem% vs each container's limits, worst first, with a recommendation
• Reclaim disk (analyze bloat / image_and_volume_bloat): dangling images + volumes + build cache as prune candidates with reclaimable bytes
• List/inspect containers, images, volumes, networks; tail logs; read stats/top
• Restart/stop/start a container, update its resource limits (reversible), remove a container, prune images/volumes, or recreate a Portainer stack — all with dry-run + double-confirm

Do NOT use when the target is a cluster orchestrator, a hypervisor, a storage appliance, a backup product, network device config, or OT/industrial equipment.

Related Skills — Skill Routing

If the user wants…	Use
Docker / Portainer single-host container ops	container-host-aiops (this skill)
A cluster orchestrator's workloads/rollouts	a cluster ops skill
Hypervisor VM lifecycle (power, snapshot, migrate)	a hypervisor ops skill
OT / industrial edge (Modbus, OPC-UA, PLC)	the industrial-aiops line

Common Workflows

1. A container is crash-looping

1. container-host-aiops doctor → confirm the socket/endpoint is reachable before you trust any read.
2. container-host-aiops analyze restart-loop → containers ranked by restart count, each with a likely cause read off the real exit code (137 OOM/SIGKILL, 143 SIGTERM, 139 segfault, 127 bad entrypoint, …), a recommended action, and a log tail.
3. container-host-aiops container logs <id> --tail 200 → read the actual crash output; container-host-aiops container inspect <id> → confirm the exit code, restart policy, and configured limits the RCA cited.
4. If the cause is memory: container-host-aiops analyze resource-pressure --mem 75 → see how close the container runs to its ceiling, then container-host-aiops manage update <id> '{"Memory": 1073741824}' --dry-run and re-run without --dry-run (double-confirm; the write captures the prior limits as its undo descriptor).
5. container-host-aiops manage restart <id> → bring it up on the new limit, then re-run analyze restart-loop to confirm the loop stopped.
6. Failure branch: if it still loops, the limit was not the cause — reverse the change with container-host-aiops undo list → undo apply <id> (restores the prior limits, not a guess) and go back to step 3 with the fresh log tail. If the container will not stop at all, manage remove <id> --force --dry-run first: force-remove is high-risk and irreversible, so read the dry-run before committing.

2. The host is out of disk

1. container-host-aiops system df → where the space actually went (images vs containers vs volumes vs build cache).
2. container-host-aiops analyze bloat → dangling images, dangling volumes, and build cache as ranked prune candidates with reclaimable bytes per item.
3. container-host-aiops image dangling and container-host-aiops volume dangling → eyeball the concrete list before deleting anything. A "dangling" volume holding data you still want is the classic way this goes wrong.
4. container-host-aiops manage prune-images --dry-run → exactly what would be removed; re-run without --dry-run (double-confirm, high risk).
5. container-host-aiops manage prune-volumes --dry-run → read this one carefully; volume pruning destroys data and records no undo. Note that Docker's default prune removes only ANONYMOUS unused volumes — the preview reports the named unused ones it will not touch as alsoUnusedNamed*; add --all to include them. Only then re-run for real.
6. container-host-aiops system df again → confirm the space came back.
7. Failure branch: pruning is not reversible. If you removed a volume you needed, the undo store cannot help — restore from your backup. The dry-run in steps 4–5 is the only safety net, which is why both are separate confirm-gated steps.

3. "Everything on this box is slow"

1. container-host-aiops overview → one-shot: platform/version, container counts by state, and the headline resource picture.
2. container-host-aiops analyze resource-pressure --cpu 80 --mem 80 → running containers ranked against their own limits, each row citing the measured percentage rather than a verdict.
3. container-host-aiops container stats <id> and container-host-aiops container top <id> → confirm the top offender at the process level before you act on it.
4. container-host-aiops system events → correlate the pressure with what changed (a recent deploy, restart storm, or image pull).
5. Act on the worst offender: manage update <id> '{"NanoCpus": 2000000000}' to cap it (dry-run first, undo-recorded), or manage stop <id> to shed it entirely.
6. Failure branch: if capping the top container just moves the pressure elsewhere, the host is genuinely undersized rather than misconfigured — reverse your change with undo apply <id> so you are not left with a half-applied limit, and take the sizing result to whoever owns capacity.

4. Stack drift after a bad deploy (Portainer)

1. container-host-aiops stack endpoints → the endpoints this Portainer manages; container-host-aiops stack list → the stacks on the one you care about.
2. container-host-aiops stack detail <stack-id> → the stack's current definition; container-host-aiops stack compose <stack-id> → the compose file it is running from.
3. container-host-aiops container list --running and container-host-aiops container restarts → which of the stack's containers are actually unhealthy versus merely restarted.
4. container-host-aiops manage recreate-stack <stack-id> --dry-run → preview the redeploy; re-run without --dry-run (double-confirm, high risk).
5. Validate with container-host-aiops overview and analyze restart-loop.
6. Failure branch: recreate-stack redeploys from the stack's stored definition — if that definition is itself the broken thing, recreating will faithfully reproduce the breakage. Fix the compose source in Portainer first, and use container-host-aiops undo list to check what the session already changed before layering another write on top.

Offline analysis (no live host)

Pass data straight to the analysis tools — restart_loop_rca(containers=[...]), resource_pressure_analysis(samples=[...]), or image_and_volume_bloat(dangling_images=..., dangling_volumes=..., df=...) — to analyse an exported dataset without connecting to a host.

Governance & Safety

The skill delivers reads and writes and records them; it does not decide whether a write is permitted. That is your agent's judgement, or the permission of the account you connect it with (a read-only Docker socket, a Portainer account without write scope — writes then fail at the server). There is no read-only switch, policy file, or approval gate.

• Audit is the guarantee, and it is not bypassable. Every operation — MCP and CLI alike — is logged to ~/.container-host-aiops/audit.db (relocatable via CONTAINER_HOST_AIOPS_HOME): params, result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.
• CONTAINER_HOST_AUDIT_APPROVED_BY / CONTAINER_HOST_AUDIT_RATIONALE are optional annotations recorded on the audit row (who/why); they are never required and never block.
• Runaway guard — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with CONTAINER_HOST_RUNAWAY_MAX=0.
• Writes support --dry-run / dry_run=True and double confirmation at the CLI; prune previews list what would be removed + reclaimable bytes.
• Mutating/reversible writes fetch the real before-state and record an inverse descriptor (stop→start, update_container→restore prior limits); irreversible ops record only the before-state.

References

• references/capabilities.md — full tool + field reference
• references/cli-reference.md — CLI command reference
• references/setup-guide.md — onboarding, credentials, and connectivity