dsh-docker

Docker tools for DeepSeek Harness: the agent can list containers, read logs, inspect images, and drive Compose projects, all through the Docker CLI already on the machine.

No daemon is required at install time. Reachability is probed per call, so a machine without Docker simply reports an unreachable engine instead of failing to load.

Install

dsh plugin --profile web add github:DevViking-Persike/dsh-docker

Restart dsh afterwards. The read-only tools are active immediately; see Compose to enable the lifecycle tools.

Tools

Tool	What it does
docker_ps	List containers. Running only by default; all: true includes stopped ones, project filters to one Compose project.
docker_images	List local images with their tags and sizes.
docker_logs	Read a container's recent output. Keeps the newest text and reports when older entries were dropped.
docker_compose_up	Start a Compose project detached and wait for its containers. Opt-in.
docker_compose_down	Stop and remove a Compose project's containers. Opt-in.

Compose lifecycle

Starting and stopping containers changes machine state, so those two tools are off by default. A deployment that wants them sets compose: true:

- id: dsh-docker
  name: 'dsh-docker'
  config:
    compose: true

Configuration

Every field is optional.

Field	Default	Meaning
cli	docker	Executable name or absolute path.
projectRoot	process cwd	Working directory for invocations, and the root relative compose paths resolve against.
compose	false	Register the Compose lifecycle tools.
inspectTimeoutMs	30000	Budget for one read (ps, images, logs).
composeTimeoutMs	600000	Budget for one Compose call; pulling images and waiting on health checks routinely outlasts a read by an order of magnitude.
maxOutputBytes	2000000	Cap on collected output of one invocation.
maxLogChars	40000	Cap on characters docker_logs emits.
defaultLogTail	200	Trailing lines read when a request states no tail.
graceMs	5000	Termination grace handed to the subprocess seam.

Model Experience

The read-only tools put one line per container or image into the model's context, not raw CLI output: state, status, image, Compose project/service, and published ports. An empty result says so explicitly rather than returning blank text, so the model does not read silence as failure.

docker_logs keeps the newest characters when it must cut, because the tail of a log is what explains a failure that just happened, and it marks the cut so the model knows it is not seeing the whole file.

Compose results lead with the settled project state and put the backend's own output after it — the model reasons about which containers are up, and reads the CLI text only when diagnosing.

Safety

• Arguments reach the executable as a fixed argv and are never shell-interpreted, so a container name cannot become a flag or a shell fragment.
• -- terminates flag parsing before every container operand, so a container literally named --follow stays an operand.
• docker_compose_down never forwards a service filter: down removes the whole project, and a filtered call would read as narrower than it is.
• Compose lifecycle calls are marked concurrency-unsafe, because two lifecycle calls on one project race inside the engine.

Known Limitations and Deferred Work

• Image sizes are parsed from the CLI's display string (1.09GB), because docker images --format json exposes no machine-readable size. An unparseable value reads as 0 rather than failing the listing.
• Engine reachability is probed on every call rather than cached, so a stopped daemon is noticed immediately at the cost of one extra invocation per tool call.
• Compose project state is read back with a second docker ps after each lifecycle call, since the CLI's own output does not report the settled containers.
• There is no docker exec, no image build, and no registry operation. Each would widen the blast radius considerably and none has a current consumer.

License

MIT — see LICENSE and NOTICE.md for attribution to the DeepSeek Harness project whose plugin conventions this follows.