DeepSeek Harness Plugins: What You Can Actually Swap, and What You Cannot

A running dsh is an ordered list of plugin rows composed at boot. Layers apply over an empty list in a fixed order: each bundle named in the profile manifest's dsh.profile.bundles, then the profile's own cordis.patch.yml, then $DSH_HOME/cordis.patch.yml, then each --patch overlay in the order it appears in argv.

The home-level file outranks the per-profile one. That ordering is deliberate, because the home file holds machine-local preferences that should apply to every profile you run.

--dump-default-config prints the bundle layers alone. --dump-config adds your patches on top. Neither boots the runtime, and both annotate each row with the file that supplied it and every overlay that changed it. Unmatched patch targets are reported on stderr, which is how you catch a typo in a row id before it costs you an hour.

One caveat when reading a dump: !!js expressions are printed unevaluated, and a dump never runs the app's command-line providers. What you see is the tree before --port or --host resolve.

A seam is a service definition declaring an interface, a provider implementing it, and consumers using it. Replace the provider row and the consumers do not change. There are 29 of these, and they are where real substitution happens: ctx.llm, ctx.fs, ctx.shell, ctx.sandbox, ctx.subagents, ctx.compaction, ctx.skills and the rest.

A core service has one owner and no expectation of an alternative implementation. You extend it by registering into it. There are 39, and the one to understand first is ctx.tools. Tools really are plugins, so the popular version of this story is broadly right, but the registry that holds them, its policy pipeline and its execution guards are core. You add a tool. You do not replace the thing tools live in.

ctx.systemPrompt behaves the same way. Plugins contribute prompt sections and model-facing tool schemas for each step, and the assembler collecting them is not yours to swap. Same for ctx.sessions, ctx.agents, ctx.commands and ctx.tokenMeter.

Exactly one service carries the bundle label, and it is ctx.agentLoop. The catalog note beside it says this is the one concrete loop plugin. There is a section further down on what that does to the claim that the loop is customizable.

The catalog is generated from the Cordis declarations by scripts/gen-doc-graphs.ts with a completeness guard, so it cannot quietly fall behind the code. Open it before you plan a change, ahead of any blog post including this one.

Two adapters ship. llm-deepseek handles DeepSeek's own API and its wire extensions. llm-pi-ai is the protocol-independent adapter that covers everyone else, and it is the package doing the work whenever you point dsh at another vendor.

For a provider dsh already knows, open Settings, then Models, then Add provider. The list shows provider ids such as anthropic, openai, moonshotai for Kimi, and zai for GLM. Enter the key and save. The installed catalog supplies the endpoint, the protocol, and the model list.

For a company gateway, a self-hosted server, or anything absent from that catalog, choose Add a custom provider. You supply a lowercase provider id, a base URL, an API protocol, a credential, and at least one model. Three protocols are offered: openai-completions for OpenAI Chat Completions, openai-responses for the OpenAI Responses API, and anthropic-messages for the Anthropic Messages API. A provider speaks exactly one of them, so a gateway serving two needs two provider entries.

Choose the provider id carefully, because it is permanent. Requests, saved sessions, model defaults and credential references all use it. Renaming means adding a new provider and deleting the old one. Everything else stays editable.

The Models page exposes only what a route needs to exist. Reasoning effort levels, image input, request-compatibility switches, headers, timeouts and retry policy all live in $DSH_HOME/settings.yaml, which is the same document the page writes. Edit it directly and the adapters pick it up on the next request with no restart.

Target a row by id and set config to replace its configuration. Target it and set disabled: true to switch it off. Or open an insert block to add rows no bundle supplied. That is the whole grammar.

Replace means replace. A patch overwrites the targeted row's complete config value rather than deep-merging keys, so a row you patch must restate every key it owns. The web bundle's own patch file carries that warning in a comment at the top, and it is worth taking seriously.

Read that same file and you will find it disabling a long list of base rows: tool-bash, tool-pwsh, tool-fs, tool-fs-search, tool-str-replace-editor, tool-skill, plan-mode, compaction-basic, tool-subagent and more. Those capabilities are not missing from the web app. They moved down into agent presets, which compose per session rather than per process.

Copy that pattern in your own configuration. Disable at the host layer, mount at the preset layer, and you get one composition per agent instead of one composition for the whole process.

This is the clearest demonstration of what a seam buys you. The filesystem and subprocess providers share one execution world, so pointing them at a remote sandbox takes the bash tool, the PTY shell and the language-server integration with them. None of those consumers is forked or even edited.

The E2B family is three packages. dsh-e2b owns one shared remote sandbox handle and its lifetime. dsh-fs-e2b and dsh-subprocess-e2b are the providers that fill ctx.fs and ctx.subprocess. No shipped composition enables the family, so this is entirely opt-in.

Three settings matter: an API key or the E2B_API_KEY environment variable, an absolute POSIX working directory that defaults to /home/user/workspace, and a lifetime in milliseconds that defaults to 300000. A bad key, a relative working directory or an invalid lifetime rejects startup before any remote work happens.

The sandbox is created when the family starts and deleted when the lifetime expires or the app shuts down. Whatever it held disappears with it. Five minutes is a short default for a real coding session, so raise timeoutMs deliberately rather than discovering the limit mid-task.

None of this reaches the model, and it adds no request cost. The agent sees one consistent remote world where what it writes with the file tools is what its commands can read.

ctx.compaction is the seam. compaction-basic is the shipped backend, and it owns thresholds, retained-tail policy, overflow caps and failure handling. Swap the row and every one of those decisions becomes yours.

Automatic compaction runs at the agent/pre-step waterfall, before request derivation, under one of two triggers: pressure or context-overflow. Recovery from a failed request runs separately through agent/request-error after the failed step closes.

Before selecting a range to summarise, the backend calls the optional tool-result pruner, which rewrites oversized current tool results into replayable replacements, then remeasures through ctx.tokenMeter. Sometimes pruning alone advances the surface and no summary is written at all. Disabling tool-result-pruner is a one-line patch if you would rather keep raw results and pay for them.

There is no model-facing compact tool. The human /compact command is backend independent, so it follows whichever compaction service the leaf mounts, and it returns without writing when no useful range exists.

Writing your own backend means implementing compactIfNeeded, compactNow and compactRegion, forwarding the supplied abort signal to summarization, and creating the replacement user message through compactCheckpointSource so clients still recognise the checkpoint. That recognition predicate is deliberately backend independent, which is what makes a custom backend viable rather than theoretical.

ctx.subagents is unusual among the seams. Multiple providers coexist in one context, registered by name, following the LLM adapter registry pattern rather than the single-executor pattern that bash uses. Delegation is one optional capability, not part of the agent loop.

Six providers ship: spawn and fork run in process, and acp, codex, claude-code and dsh-sdk run out of process through ctx.subprocess. fork seeds the child with the parent's completed-turn prefix; spawn and acp do not. That flag describes conversation seeding only and says nothing about inherited tools, services or authority.

The base bundle mounts spawn and fork, then registers two tools: subagent on the spawn provider in continuable mode, and subagent_fork on fork in one-shot mode. Fork deliberately omits model selection so the child's provider and model match the parent, which keeps the inherited history eligible for cache reuse.

Codex and Claude Code are separate optional bundles. Install either or both with dsh plugin. On the next start each installed bundle registers only its dormant host provider, so a copied preset must separately enable the matching tool row before new agents can delegate to it.

Providers advertise their start-time features on a static descriptor: agentOptions, outputSchema, depthLimit, toolFilter and persona. A request needing a capability the chosen provider lacks is rejected with an UNSUPPORTED_CAPABILITY error rather than accepted and quietly ignored. The ACP, Codex and Claude Code backends reject agentOptions before they start their transports, so plan around that rather than against it.

An agent preset is a directory holding a single agent.cordis.yml that names the plugins a session runs with: its tools, its prompt sections, its skills. Sessions naming the same preset share one installed composition while each session's state stays separate, so one process can run several differently composed agents at once. A subagent joins its parent's composition.

Four presets ship: minimal, standard, ptc and cordis. Read minimal first, because it is the most instructive file in the repository. It sets a fixed persona with complete: true so nothing else can add prompt text, suppresses runtime context snapshots, mounts one persistent shell plus str_replace_editor, and omits compaction entirely. That is an entire coding agent in about forty lines.

Presets come from two roots. The set shipped inside the package is prepended as a system root, and your own live under $DSH_HOME/.agent-presets. The shipped root wins duplicate ids unless you set includeShippedRoot to false, which is the escape hatch for a deployment supplying every preset itself.

Authoring is copy-only by design. You copy an existing preset's whole directory into the first user root, give it an id matching [a-z0-9][a-z0-9-]*, then edit the files. A copy never overwrites, and it grants nothing the roster did not already carry.

One rule catches everyone on their first preset. A service row inside a preset must sit inside a group carrying an isolate realm. Without one it publishes into the root realm where it is process-global, another preset publishing the same name collides, and dsh-agent-presets rejects the mount rather than letting one preset's instance serve every session.

A session can switch presets only while it has produced nothing. After the first message or tool call the composition is fixed for that session's life, because swapping tools mid-conversation would leave logged tool calls the new composition cannot make. A committed switch is recorded in the session log, so a resumed or forked session rebuilds under the composition it actually ran.