In the DeepSeek Harness ecosystem, agents often lack direct tooling support when interacting with a local Docker environment. Manually writing scripts or making external calls is inefficient. The dsh-docker plugin wraps the local Docker CLI, enabling agents to directly list containers, view logs, manage images, and start Compose projects.

What Is This

dsh-docker is a DeepSeek Harness plugin that provides Docker container, image, log, and Compose tools for agents to use via the local Docker CLI.

The plugin is maintained by DevViking-Persike and is open-sourced under the MIT license. It does not require starting an additional daemon during installation. Each invocation probes the reachability of the Docker engine, so even if the machine has no Docker, the plugin does not fail at load time; instead, it reports an unreachable status.

Core Features

The plugin provides the following tools:

  • docker_ps: Lists containers. By default, it shows only running containers. Use all: true to include stopped containers, and use the project parameter to filter a specific Compose project.
  • docker_images: Lists local images with their tags and sizes.
  • docker_logs: Reads recent output from a container. The plugin retains the latest text and reports when older entries are truncated. Empty results are explicitly reported to prevent the model from misreading silence as failure.
  • docker_compose_up: Starts a Compose project (in detached mode and waits for containers to be ready). This feature is disabled by default and must be enabled in the configuration.
  • docker_compose_down: Stops and removes containers for a Compose project.

Installation and Enablement

Install it with the official command:

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

After installation, you need to restart dsh. The read-only tools (ps, images, logs) are available after the restart. If you need to use the Compose lifecycle tools, enable them in the configuration.

Configuration and Usage

Compose Tool Enablement

In the DSH configuration file, set compose: true to activate the Compose start and stop tools:

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

Configuration Parameters

All configuration options for the plugin are optional. Common parameters include:

Field Default Description
cli docker Executable file name or absolute path for Docker.
projectRoot current working directory of the process Working directory for invocations and the root directory for resolving Compose paths.
compose false Registers the Compose lifecycle tools.
inspectTimeoutMs 30000 Timeout for a single read-only operation (ps, images, logs).
composeTimeoutMs 600000 Timeout for a single Compose invocation (used for pulling images and waiting for health checks).
maxOutputBytes 2000000 Maximum output collection size for a single invocation.
maxLogChars 40000 Maximum number of characters in docker_logs output.
defaultLogTail 200 Number of trailing lines to read when the tail parameter is not specified.
graceMs 5000 Termination grace period passed to child processes.

Security and Model Experience

  • Parameter handling: Parameters are passed to the executable as fixed argv entries and are not interpreted by a shell, so container names cannot become shell fragments or flags. The -- terminator ensures that container names such as --follow are not misparsed.
  • Model experience: The plugin does not feed raw CLI output directly to the model. Instead, it organizes state into a single-line format (state, status, image, project/service, ports). Compose results prioritize showing the settled project state, and backend CLI output is read only during diagnostics.

Notes and Limitations

Security

  • The plugin does not support docker exec, image builds, or registry operations, because these operations would significantly expand the security risk surface.
  • docker_compose_down does not support service filters; it removes the entire project.

Functional Limitations

  • Not concurrency-safe: Compose lifecycle tools are marked as not concurrency-safe. Concurrent invocations on the same project can cause race conditions.
  • Image size parsing: Image sizes are parsed from CLI display strings (such as 1.09GB) because docker images --format json does not provide machine-readable sizes. Unparsable values are displayed as 0.
  • State checks: After a Compose lifecycle invocation, an additional docker ps is needed to read the project’s settled state, because the CLI output itself does not report settled containers.

Ecosystem Note

The philosophy of DeepSeek Harness is “everything is a plugin.” The community catalog (catalog_url) where this plugin resides has no official affiliation with DeepSeek or High-Flyer. Please review the source code and license before use.