Talking to this machine's container engine

Nine tools, one engine, one rule: state first, then the smallest verb that answers the question. The tools speak the docker CLI, or podman when docker is not on PATH; every verb below works the same on both.

question	tool
is there an engine, and is it awake? what does it hold?	docker_state
what is running / what exists?	docker_ps
which images are on disk?	docker_images
what exactly is this container or image?	docker_inspect
what did it print?	docker_logs
fetch an image	docker_pull
start a container from an image	docker_run
start / stop / restart / pause / unpause / remove / prune	docker_action
turn Docker Desktop or a podman machine on	docker_start

The order to call them in

1. docker_state. It is the only tool that treats a sleeping engine as an ANSWER instead of a failure. On Windows 11 the engine is Docker Desktop, and Desktop being closed is the normal state after a reboot: docker_state says so, in the engine's own words, and tells you whether docker_start can fix it or whether the machine needs sudo systemctl start docker (which this plugin will not run for you).
2. docker_start when the state says the engine is down and startable. It launches Docker Desktop (or runs podman machine start) and then polls the daemon - not the app - for up to 90 s. A cold Desktop start can be slow: if it times out, call docker_state again in a minute rather than docker_start twice.
3. docker_ps / docker_images for the lists. Get the exact name or id from here; every other tool takes it verbatim.
4. docker_inspect when you need the facts (ports, mounts, exit code, restart policy) and docker_logs when you need the words. tail defaults to 200; since: "10m" narrows it.
5. docker_pull before docker_run when the image is not there yet - or let docker_run pull it, which docker does itself. Pulling first is what makes a slow download and a failed start two separate, readable events.
6. docker_run to start one, docker_action to change one.

The calls, with the shape that works

docker_state({ disk: true })                      # the full picture, with disk use
docker_ps({ all: false, filter: "postgres" })     # what is running, narrowed
docker_images({ filter: "nginx" })
docker_inspect({ id: "web" })                     # kind is inferred; pass it to be explicit
docker_logs({ id: "web", tail: 200, since: "10m" })
docker_pull({ image: "postgres:16" })
docker_run({ image: "postgres:16", name: "db", ports: ["127.0.0.1:5432:5432"],
             env: { POSTGRES_PASSWORD: "dev" }, volumes: ["db-data:/var/lib/postgresql/data"] })
docker_action({ action: "restart", id: "web" })
docker_action({ action: "remove", id: "web", confirm: "web" })   # confirm REPEATS the id
docker_action({ action: "prune", kind: "image", confirm: "prune" })

What the tools will not do, and why

• No exec. A container shell is a shell; the harness already has one, under the session's approval policy. If a person asks you to run something inside a container, say what the command is and run it through the shell tool - do not look for a docker_exec.
• No system prune. prune here means stopped containers or DANGLING images, one kind at a time. docker system prune -a also takes networks, build cache and every unused image, and one confirmation cannot honestly cover that.
• No free-form run. docker_run builds its argv from a schema; there is no spelling for --privileged, --pid host, --device or a relative host path. If a container genuinely needs one of those, say so to the person instead of working around the tool.
• No latest by accident. An image reference without a tag is latest; if the person did not name a tag, name one you know exists or write latest out loud so the choice is visible.
• Nothing outside the engine. No compose, no network create, no volume remove. Compose files belong to the repository and the shell.

Removing things without regret

remove needs confirm set to the SAME id or name. That is not red tape: the container's writable layer disappears, and an image may need a pull to come back. So before a removal:

1. docker_ps and read the row - is it running? did you start it?
2. docker_inspect for its mounts; a bind mount holds data the container does not, and a named volume survives the container anyway.
3. Ask, when the container is not yours: "remove web?" is one sentence, and a person's "yes" is what confirm is standing in for.
4. docker_action({ action: "remove", kind: "container", id: "<name>", confirm: "<name>" }).

force: true is for a running container that must go now. It is the difference between a clean stop and a pull of the plug; do not pass it by default.

When the engine says no

answer	what it means	what to do
NO_CLI	no docker and no podman on PATH	say so; offer the install; DSH_DOCKER_CLI pins a binary outside PATH
ENGINE_DOWN	the CLI is there, its daemon is not	docker_start, or the system command docker_state printed
CONFIRM_REQUIRED	a removal without confirm	pass confirm — and only after the person agreed
BAD_ARG	a value the grammar refused (an id starting with -, a bad port)	re-read the row's id; do not "fix" it by guessing
FAILED	the engine ran the command and refused	the message is the engine's own sentence; read it before retrying
TIMEOUT	the call outlived its deadline and was killed	check the daemon; a pull can legitimately need a longer wait

More detail - platform start paths, Podman's differences, stream separation, image references and a safe-removal checklist - is in reference/lifecycle.md.