Introduction

When enabling agents in DeepSeek Harness (DSH) to execute GPU tasks, common problems arise: querying status, selecting cards, executing commands, and managing background tasks all rely on manual shell string concatenation. While directly calling nvidia-smi or manually setting CUDA_VISIBLE_DEVICES works, selecting multi-GPU cards, managing background jobs, and concurrent selection logic become scattered.

Below is an introduction to dsh-gpu. It is a GPU-aware execution layer for DeepSeek Harness: providing three tools, gpu_status, gpu_exec, and gpu_run_bg, supporting optional per-step GPU context injection, and automatically handling CUDA_VISIBLE_DEVICES card selection.

What is it

dsh-gpu is a DeepSeek Harness plugin positioned as a GPU-aware execution layer for DeepSeek Harness. It encapsulates GPU status queries, GPU command execution, and GPU background jobs into the DSH tool layer, licensed under MIT.

Repository URL:

https://github.com/zytsyj/dsh-gpu

Core Features

gpu_status: Query all GPU status at once

gpu_status is used to query all devices at once, returning:

  • memory used/total
  • SM utilization
  • temperature
  • free/busy verdict

A device is considered busy if any of the following conditions are met:

  • memory used reaches or exceeds 80%
  • utilization reaches or exceeds 50%

Both thresholds are configurable.

gpu_exec: Execute one-off GPU commands

gpu_exec is used for one-off commands. It sets CUDA_VISIBLE_DEVICES based on the current card selection result and executes the command via the DSH-mounted ctx.shell executor.

It supports:

  • automatically selecting a less busy card
  • explicitly specifying a card
  • selecting count cards for multi-GPU commands

gpu_run_bg: Run long-running GPU tasks in the background

gpu_run_bg is used for long-running tasks such as training, inference services, and benchmarks. The task is registered as a gpu job to ctx.jobs and returns the job ID immediately.

Afterwards, you can:

  • use job_output to read output
  • use job_kill to stop the task

It requires the jobs service to be enabled in the composition:

@deepseek-ai/dsh-jobs
@deepseek-ai/dsh-tool-jobs

Per-step context: Inject a line of GPU snapshot for eligible steps

Per-step context is an optional capability, enabled by default. It injects a line of GPU snapshot for eligible steps and is rate-limited to one sample per minute.

Installation and Enablement

First, determine the DSH profile to enable the plugin for, then execute the plugin installation command:

dsh plugin --profile <name> add dsh-gpu

Here, <name> is a profile placeholder, replace it with the current profile name.

Regarding loading order, it is recommended to place dsh-gpu after the execution-world plugin. For example, if DSH provides the shell seam via the SSH provider plugin, dsh-gpu should be placed after that plugin to ensure it queries the expected shell seam.

Typical Usage

Below are the call paths organized based on verified capabilities:

  1. First, call gpu_status to view the current GPU’s memory used/total, SM utilization, temperature, and free/busy verdict.
  2. Call gpu_exec for one-off GPU commands. The plugin will set CUDA_VISIBLE_DEVICES and execute the command via the ctx.shell executor.
  3. Call gpu_run_bg for long tasks like training, inference services, and benchmarks. After obtaining the job ID, use job_output to read the output and job_kill to stop the task.
  4. If you need to see GPU status at every step, keep the default per-step context, which will inject a line of GPU snapshot at a rate limit of one sample per minute.

If stronger determinism is required, you can read gpu_status first within the same step, then explicitly pin gpuIndex.

Use Cases and Considerations

dsh-gpu is suitable for scenarios where GPU execution logic needs to be integrated into DSH agents, such as:

  • querying GPU status
  • executing one-off GPU commands
  • running background tasks like training, inference services, and benchmarks
  • automatically selecting a less busy card in a multi-GPU environment

The following points need attention:

  • nvidia-smi ignores CUDA_VISIBLE_DEVICES and always reports physical indices. gpu_exec’s card selection for CUDA programs still works as designed, but do not use nvidia-smi output to verify pinning.
  • Card selection is advisory, not a reservation. Two concurrent agents may still select the same card. If exclusive access is required, you must read from gpu_status and pin gpuIndex within the same step.
  • gpu_run_bg depends on the jobs service. The composition must include @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs.
  • On a host without NVIDIA GPUs, gpu_status reports a clean no-GPU result instead of failing.
  • The plugin integrates into the execution chain of the current DSH profile and uses the mounted shell executor with the current dsh process permissions. You should check the source code and MIT license before installation.

Conclusion

The value of dsh-gpu lies in converging GPU status queries, command execution, and background jobs into the DSH tool layer, reducing the repetitive logic where agents manually check cards, splice environment variables, and poll background tasks.

Repository URL:

https://github.com/zytsyj/dsh-gpu