DSH Carrot on a Stick

A DSH plugin that exposes DSH operations through the MCP protocol。

MCP features

Tools

Resources

Resource-capable clients can read the same data without spending tokens, and subscribe to changes instead of polling:

resources/subscribe pushes task status transitions, turn-end history refreshes, and live activity over SSE — no polling. Setting resourceFirst: true in the config retires the nine read-only tools and returns results as resource references (for clients confirmed to support MCP resources; default false keeps tools and resources coexisting).

Related MCP server: hermes-dsh-bridge

Everyday patterns

One-off task — synchronous, structured summary back; continue later with sessionId (send only the delta in context):

{ "name": "agent_run", "arguments": { "task": "fix the failing test in src/auth", "cwd": "/workspace/app" } }

Background queue — submit, poll cheaply, fetch once done:

{ "name": "task_inbox",   "arguments": { "task": "…", "cwd": "/workspace/app" } }
{ "name": "task_result",  "arguments": { "taskId": "…", "detail": "status" } }
{ "name": "task_cancel",  "arguments": { "taskId": "…" } }
{ "name": "task_result",  "arguments": { "taskId": "…" } }

Sessions — session_list to find one, session_history to read it, select_model to switch its model, agent_steer to redirect it mid-run.

Models & presets

• Priority: per-call arguments > plugin config > host default. A half-set pair completes from the lower source; unresolvable calls fail loudly.

• Three ways to change models: per-call provider+model · select_model mid-conversation · pin via config with allowModelOverride: false. Presets (preset argument, for new sessions) work the same way under allowPresetOverride.

• Sessions are pooled per cwd + model + preset: same directory, different model/preset → a separate session. Taking over a session keeps its model and preset.

• Continuing by sessionId runs in the session's own directory; an explicitly passed cwd must match it.

Result size — detail controls token cost: summary (default, a few hundred tokens) / normal (~2k) / full (debugging); task_result adds a status level for polling. Results are structured (sessionId, model, changes, verification, leftovers, …); failures come back with isError: true.

Configuration (cordis.yml)

- insert:
      - id: dsh-carrot-on-a-stick
        name: 'dsh-carrot-on-a-stick'
        config:
            http: true
            port: 8090
            host: 127.0.0.1 # localhost only by default; add auth before exposing
            # authToken: 'your-secret-token'
            # workspaceRoots: ['/workspace']   # cwd whitelist (also gates session surfaces)
            # allowedHosts: ['my-box.lan']     # extra allowed Host header values
            # preset: 'standard'               # agent preset to mount
            # model: ''                        # pair with provider; empty = follow host default
            # provider: ''
            # reasoningEffort: ''              # empty = adapter default
            # allowModelOverride: true         # false = pin the model
            # allowPresetOverride: true        # false = pin the preset
            # queuePersistPath: '.dsh/queue.json'
            # queuePersistKey: 'passphrase'    # encrypt the persistence file
            # sessionTtlMs: 86400000

Security

⚠️ This plugin exposes local code execution (equivalent to RCE). It binds 127.0.0.1 only. When enabling:

1. Set authToken — protects against other local processes and DNS rebinding;

2. Set workspaceRoots — without it there is no directory boundary at all; with it, execution and session reads (list / history / steer / takeover) are both constrained;

3. Never bind 0.0.0.0 or expose to LAN/WAN without a reverse proxy + TLS + auth.

Built-in guards: Host- and Origin-header allowlists (DNS-rebinding guard), HTTP surface limited to /mcp, 401 answers with a Bearer challenge, idle transport sessions reaped after sessionTtlMs. Note that spawned sessions follow the host/preset approval policy — this plugin runs unattended, so ask-style policies may pop dialogs or fail closed; verify sensitive operations under your preset before deploying. If you enable queuePersistPath, task payloads are written to that file (plaintext unless queuePersistKey is set) — choose a location with appropriate permissions.

Web settings panel

The bundle adds a Settings → dsh-carrot-on-a-stick section to the dsh web UI: live status badge, the MCP endpoint (click to copy), start/stop buttons, connected client list, and queue counters.

Known limitations

• Spawned sessions follow the host/preset approval policy — ask-style policies may pop a dialog or fail closed in unattended use.

• select_model requires the web profile's sessionController; headless deployments fall back to the model catalog plus per-call overrides.

• dsh_list_tools only lists the host-global registry; per-agent tool visibility needs a host-side API.

• Without queuePersistPath the queue lives in memory and is lost on restart.

Acknowledgements

Started as a copy of chushixixin/dsh-harness-mcp-server (MIT, thanks @chushixixin), now an independent project.