containers

Check what is actually installed first

docker and podman take nearly the same arguments and are not the same thing. run_command "docker version" — if it is absent, run_command "podman version", because a machine with Podman answers docker commands only when the alias package is installed. Do not assume; one list_commands or version call saves a turn of confusing errors.

If the daemon is not running, that is service_control docker status and not a docker problem.

Anything that pulls or builds is a job

An image pull and a build are minutes, not seconds:

job_start   docker build -t myapp:dev .
job_wait

A wait that times out has not cancelled the build — call job_wait again. Starting a second build because the first "timed out" gives you two builds competing for the same layer cache, which is slower than either alone.

Reading a container that is misbehaving

In this order, because each answers a different question:

• run_command "docker ps -a" — is it running, or did it exit? An exit code of 0 means it finished; 137 means it was killed (usually OOM); 125/126/127 mean Docker could not run the command at all.
• run_command "docker logs --tail 100 <name>" — what it said. The tail, not the head: the reason it died is at the end.
• run_command "docker inspect <name>" — large, and worth spilling. Read the bits you need with a format string instead: docker inspect -f '{{.State.Health.Status}}' <name>.
• run_command "docker stats --no-stream" — memory against its limit. A container restarting in a loop is usually hitting one.

--no-stream and --tail are not optional. docker stats and docker logs -f never return, so without them you have started something that must be a job and is not one.

Exec is a terminal, not a command

docker exec -it wants a TTY nothing here provides. Use -i alone, or better, docker exec <name> <cmd> with no flags for a one-shot. For a genuinely interactive session, open a shell (shell_open) and drive it — that is what the shell tools are for.

Compose

docker compose (space) on anything current; docker-compose (hyphen) is the old standalone binary and may not be there. run_command "docker compose config" validates and prints the resolved file — do that before up when a variable is involved, because Compose substitutes silently and an empty variable becomes an empty string rather than an error.

docker compose up -d, then check: up returning 0 means the containers were created, not that the app works.

Cleaning up, carefully

docker system prune is destructive in the way that matters — -a removes images nothing is running right now, including the one somebody was about to start, and --volumes removes data. Show what would go first (docker system df), say what you are about to remove, and ask. This is the command that turns "the disk was full" into "the database is empty".

Hardening, when asked

The short list that matters: do not run as root inside the container (USER in the Dockerfile), do not mount the Docker socket into a container you do not fully trust — that is root on the host — drop capabilities you do not need, pin image tags rather than :latest so a rebuild is reproducible, and keep secrets out of the image (they persist in layers even if a later layer deletes them).

A credential in a build argument or an ENV is baked into the image. That is the container version of the rule in your system prompt: it does not belong in an argument.