[READ] Find crash-looping containers and map each to a cause + action.

The flagship restart RCA: inspects containers for restart count + exit code, flags the crash-looping ones (restartCount >= threshold, or restarting/dead, or a non-zero exit), attaches a likely cause + recommended action from the exit code (137 OOM/SIGKILL, 143 SIGTERM, 139 segfault, 127 bad entrypoint, …), and a tail of logs. Every ranking carries its numbers. Pass 'containers' for pure analysis, or a target to pull live.

Args: restart_threshold: Restart count at/above which a container is looping (default 3). containers: Injected rows {id, name, state, restartCount, exitCode, oomKilled, error}; skips live collection. logs_by_id: Optional {containerId: [logLine, ...]} log tails to attach. target: Target name from config; omit for the default.

[READ] Rank containers by CPU/memory pressure vs their limits + recommend.

Pulls a one-shot CPU%/mem% sample for each running container (or uses injected 'samples'), flags each 'near' (>= 80% of a threshold) or 'over' (>= threshold), and attaches a recommendation (raise a limit, set a missing memory limit, scale out). Ranks worst-first by the higher of CPU%/mem%. Every row carries its numbers.

Args: cpu_threshold: CPU% at/above which a container is over pressure (default 80). mem_threshold: Memory% at/above which a container is over pressure (default 80). samples: Injected rows {id, name, cpuPercent, memPercent, memUsageBytes, memLimitBytes}; skips live collection. target: Target name from config; omit for the default.

[READ] Total dangling images + volumes + build cache into prune candidates.

Sums dangling images, dangling volumes, and build cache (from system/df) into reclaimable-byte prune candidates, largest first. Pass the three read payloads for pure analysis, or a target to pull live.

Args: dangling_images: Injected {danglingCount, reclaimableBytes, ...}; skips live. dangling_volumes: Injected {danglingCount, reclaimableBytes, ...}; skips live. df: Injected system/df summary {buildCache:{count, totalBytes}, ...}. target: Target name from config; omit for the default.

[READ] List containers, bucketed by state, with compact rows.

Args: all_states: True (default) lists all containers; False only running. target: Target name from config; omit for the default.

[READ] Full inspect of one container (config, state, mounts, network).

Args: container_id: Container id or name. target: Target name from config; omit for the default.

[READ] Tail the last N log lines of a container (stdout + stderr).

Args: container_id: Container id or name. tail: Number of lines from the end (1..2000, default 100). target: Target name from config; omit for the default.

Returns an envelope: {"lines": [...], "returned": N, "limit": L, "truncated": bool}. When "truncated" is true the container has older log history than was returned — re-run with a higher tail rather than treating this as the container's complete log.

[READ] One-shot CPU%/memory% snapshot for a container (stream=false).

Args: container_id: Container id or name. target: Target name from config; omit for the default.

[READ] Processes running inside a container (like docker top).

Args: container_id: Container id or name. target: Target name from config; omit for the default.

[READ] Restart-count + exit-code summary across containers, worst-first.

Args: all_states: True (default) inspects all containers; False only running. target: Target name from config; omit for the default.

[READ] List images (tags, size, dangling), largest first.

Args: all_images: True includes intermediate layers; default only top-level. target: Target name from config; omit for the default.

[READ] Inspect an image plus its build history (layers, sizes, commands).

Args: image_id: Image id or name:tag. target: Target name from config; omit for the default.

[READ] Untagged (dangling) images + reclaimable bytes — prune candidates.

Args: target: Target name from config; omit for the default.

[READ] Image disk usage from system/df (total, shared, reclaimable).

Args: target: Target name from config; omit for the default.

[READ] List Docker networks, bucketed by driver.

Args: target: Target name from config; omit for the default.

[READ] Inspect one network (driver, IPAM subnet/gateway, attached containers).

Args: network_id: Network id or name. target: Target name from config; omit for the default.

[READ] List Podman pods (Podman-only): id, name, status, member containers.

A pod groups containers sharing namespaces — a Podman-native concept with no Docker equivalent, read over the libpod API. Requires a podman target; on a docker/portainer target it returns a teaching error (pods do not exist there).

Args: target: Target name from config; omit for the default.

[READ] Portainer endpoints (managed hosts): id, name, type, status, url.

Requires a portainer target.

Args: target: Target name from config; omit for the default.

[READ] Portainer stacks (Compose/Swarm): id, name, type, endpoint, status.

Requires a portainer target.

Args: target: Target name from config; omit for the default.

[READ] One Portainer stack in detail (env, entrypoint, resource control).

Requires a portainer target.

Args: stack_id: Portainer stack id. target: Target name from config; omit for the default.

[READ] Group containers into Compose projects with a per-stack health rollup.

Reconstructs docker compose / podman compose projects from the 'com.docker.compose.project' label over the Docker-compat layer, so it works on a docker OR podman target (no Portainer needed). Each stack rolls up to healthy (all running) / degraded (some) / down (none).

Args: target: Target name from config; omit for the default.

[READ] One-shot host overview: version + container state rollup + disk.

Call this first to triage a container host before drilling into a specific container, image, or volume.

Args: target: Target name from config; omit for the default.

[READ] Daemon info: container/image counts, storage driver, kernel, resources.

Args: target: Target name from config; omit for the default.

[READ] Docker version details (API version, Go version, components).

Args: target: Target name from config; omit for the default.

[READ] Disk-usage breakdown: images, containers, volumes, build cache.

Args: target: Target name from config; omit for the default.

[READ] Recent daemon events over the last N seconds, rolled up by type+action.

Args: since: Look-back window in seconds (1..86400, default 3600). event_type: Filter to one event type (container/image/volume/network); omit for all. target: Target name from config; omit for the default.

Returns an envelope: {"events": [...], "returned": N, "limit": L, "truncated": bool, "total": T}. When "truncated" is true only the most recent events fit — narrow the window with a smaller "since".

[READ] List recorded, not-yet-applied undo tokens (most recent first).

Each entry names the original tool, the inverse tool that undo_apply would run, and a human note. Use the undoId with undo_apply.

Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra row is fetched), not guessed from a length coincidence: when it is true there are MORE tokens than shown, so re-run with a higher limit rather than reporting the list as complete.

Each entry carries effectVerified. False means the original write lost its response, so the change it reverses is PROBABLE, not confirmed — check the live state before applying, and do not report the result as a restore of a state that may never have been reached.

Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.

[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.

The inverse runs through its own governed tool, so it is audited on the same path as any other call. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.

Args: undo_id: The undoId from undo_list (or an _undo_id in a write result). dry_run: If True, preview the inverse tool + params without running it. target: Passed through to the inverse tool when it accepts a target.

[READ] List named volumes (name, driver, mountpoint, scope).

Args: target: Target name from config; omit for the default.

[READ] Inspect one named volume (driver, mountpoint, options, usage).

Args: name: Volume name. target: Target name from config; omit for the default.

[READ] Dangling volumes (unreferenced) + reclaimable bytes — prune candidates.

Args: target: Target name from config; omit for the default.

[WRITE][risk=medium] Restart a container (captures prior state for audit).

A restart has no meaningful inverse, so no undo is recorded. Pass dry_run=True to preview.

Args: container_id: Container id or name. timeout: Seconds to wait for graceful stop before killing (default 10). dry_run: If True, preview without restarting. target: Target name from config; omit for the default.

[WRITE][risk=medium] Stop a running container. Inverse: start it.

Captures whether it was running so the harness records a start undo. Pass dry_run=True to preview.

Args: container_id: Container id or name. timeout: Seconds to wait for graceful stop before killing (default 10). dry_run: If True, preview without stopping. target: Target name from config; omit for the default.

[WRITE][risk=medium] Start a stopped container. Inverse: stop it.

Pass dry_run=True to preview.

Args: container_id: Container id or name. dry_run: If True, preview without starting. target: Target name from config; omit for the default.

[WRITE][risk=high] Remove a container (captures full inspect first). No undo.

The complete inspect JSON is captured before deletion for the audit trail; there is no clean inverse for a removed container. Pass dry_run=True to preview.

Args: container_id: Container id or name. force: Force-remove a running container (SIGKILL). remove_volumes: Also remove anonymous volumes attached to it. dry_run: If True, preview without removing. target: Target name from config; omit for the default.

[WRITE][risk=high] Prune images (dangling by default). No undo.

dry_run LISTS the images that would be removed and the reclaimable bytes before doing anything.

Args: dangling_only: True (default) prunes only untagged images; False also prunes images unused by any container. dry_run: If True, list what would be removed + reclaimable bytes. target: Target name from config; omit for the default.

[WRITE][risk=high] Prune unreferenced volumes. No undo.

Docker removes only ANONYMOUS unused volumes by default (its behaviour since 23.0); named unused volumes survive unless all_unused is set. The dry_run preview is scoped by the same flag, so it describes the call you are about to make — and when scoped to the default it still reports the named unused volumes it will not touch (alsoUnusedNamed*) rather than hiding that space.

Args: all_unused: Also remove NAMED unused volumes (docker volume prune -a). Irreversible, and named volumes usually hold data someone meant to keep. dry_run: If True, list what would be removed + reclaimable bytes. target: Target name from config; omit for the default.

[WRITE][risk=medium] Update a container's resource limits, capturing prior limits.

Captures the current CPU/memory HostConfig limits before the change so the harness records an undo (restore the prior limits). Pass dry_run=True to preview.

Args: container_id: Container id or name. resources: Resource limits to set — allowed keys: Memory, MemorySwap, MemoryReservation, NanoCpus, CpuQuota, CpuPeriod, CpuShares, CpusetCpus, CpusetMems (Docker update fields). dry_run: If True, preview without changing. target: Target name from config; omit for the default.

[WRITE][risk=high] Redeploy (recreate) a Portainer stack. No undo.

Captures the stack definition for audit before Portainer recreates it; there is no clean inverse for a redeploy. Requires a portainer target. Pass dry_run=True to preview.

Args: stack_id: Portainer stack id. endpoint_id: Endpoint id the stack runs on; omit to use the stack's own. dry_run: If True, preview without recreating. target: Target name from config; omit for the default.