Introduction

The DSH plugin model breaks down local capabilities into installable, callable tools. For agent workflows, common needs include querying containers, viewing logs, executing commands inside containers, restarting containers, or cleaning up containers. If agents directly assemble shell commands, it easily introduces parameter injection, accidental operations, and missing approvals.

Below introduces dsh-docker: a DSH container management plugin that runs Docker CLI via the official subprocess service, uses an argv array to avoid shell injection, and retains the default approval gate for docker_exec.

The repository is STARDUSTLC666/dsh-docker, the npm package name is @stardustlc/dsh-docker, and the license is MIT.

What is it

One-sentence positioning: dsh-docker is a DSH container management plugin that provides six Docker tools, covering container listing, image listing, log viewing, container details, execution inside containers, and lifecycle management.

It primarily solves the problem of “allowing agents to securely view and manipulate local Docker objects.”

Runtime requirements are as follows:

  • Node version: >=22
  • Docker installed locally, and docker version produces a result
  • Verified on @deepseek-ai/dsh@0.1.2-alpha.2 (2026-08-31)
  • Zero runtime dependencies

If the Docker executable is not in PATH, it can be specified via dockerPath.

Core Features

dsh-docker exposes six tools:

Tool Purpose Description
docker_ps List containers Can filter container info
docker_images List local images Can view dangling images
docker_logs View log tails Line count is capped, can short-term follow
docker_inspect View container details Used to get container status and details
docker_exec Execute command inside container Default approval gate, with container name validation
docker_manage Container lifecycle management Supports start / stop / restart / rm

All Docker CLI calls go through the official subprocess service and use an argv array to pass parameters, avoiding shell injection.

Installation and Usage

First, confirm that Docker is available on the local machine:

docker version

If it outputs results, it means the local machine already has a usable Docker CLI.

Next, install the plugin to the web profile:

dsh plugin --profile web add @stardustlc/dsh-docker

If the docker executable is not in PATH, dockerPath can be specified in the plugin configuration. For example:

dockerPath: <docker-executable>

Here, <docker-executable> should be replaced with the path to the Docker CLI in the current environment.

After uninstalling, the Web service needs to be restarted. If a thorough cleanup is needed, manually delete the plugin line covered by cordis.patch.yml in your own profile.

Typical Usage

Below are basic invocation examples for the six tools:

docker_ps {}
docker_ps { all: true, name: web }
docker_images { dangling: true }
docker_logs { container: web, tail: 200 }
docker_inspect { container: web }
docker_exec { container: web, command: 'df -h' }
docker_manage { container: web, action: restart }

A few key points:

  • docker_exec has the approval gate enabled by default.
  • In a headless environment without an approval channel, docker_exec will reject execution.
  • Container name validation only allows [A-Za-z0-9][A-Za-z0-9_.:-]*.
  • Single operation timeout is capped between 5 seconds and 10 minutes.
  • Follow mode is additionally limited to 30 seconds.
  • The tail parameter of docker_logs is limited between 1 and 2000 lines.

Applicable Scenarios and Notes

This plugin is suitable for developers or operations scenarios who have Docker installed locally and want DSH agent workflows to directly view container status.

Common uses include:

  • Use docker_ps to quickly confirm which containers are running.
  • Use docker_images to check local images and dangling images.
  • Use docker_logs to view the last 200 lines of logs for a specific container.
  • Use docker_inspect to get container details.
  • Use docker_manage to perform lifecycle operations like restart or stop.

Be aware of the following limitations:

  • The plugin will execute Docker commands with the permissions of the current DSH process; source code and license should be checked before installation.
  • docker_exec will execute commands inside the container and requires approval by default.
  • rm in docker_manage is a destructive operation; the target container must be confirmed before execution.
  • docker_exec will be rejected in a headless environment without an approval channel; this is expected behavior.

Related Links

  • Community Directory: https://www.skillhub.cn/plugins/STARDUSTLC666/dsh-docker
  • GitHub: https://github.com/STARDUSTLC666/dsh-docker