Quick Answer
DeepSeek Harness (dsh) has one architectural claim: everything is a plugin. The filesystem, the shell, the model adapter, the Web UI, and sub-agents are not hardcoded — they are swappable plugins, orchestrated by a runtime called Cordis.
This isn't decoration. It directly yields dsh's three capabilities: a trimmable capability surface, swappable providers, and customizable tools. Let's unpack it.
What Cordis Is
Cordis is the plugin runtime that drives dsh (its design is described in the paper A Programming Paradigm for Spatiotemporal Composability). Two ideas capture it:
- Registrations are reversible effects — prompt sections, tool schemas, adapters, providers, and listeners are installed via
ctx.effect()orctx.on(), so reload and teardown unwind them predictably. - Spatiotemporal composability — different plugins compose in one context by declaration order; capabilities stack and unstack.
You don't need to read Cordis source. Just remember: dsh's capability = the combination of plugins you load. Add a plugin to gain ability, remove one to lose it.
Seams: The "Three-Role" Swappable Capability
One word recurs in dsh's docs — seam (a swappable capability). It's the mechanism behind "swap one provider and change the whole product."
A seam has three roles:
| Role | Responsibility | Example (shell) |
|---|---|---|
| Service Definition | Declares the interface | dsh-shell |
| Service Provider | Implements it | dsh-bash-local (local) / dsh-bash-sandbox (sandbox) |
| Consumer | The model-facing tool that uses it | dsh-tool-bash |
The same structure runs through the whole framework: the model provider (register an adapter on ctx.llm), the filesystem (ctx.fs), the web runtime (ctx.web), sub-agents (ctx.subagents).
Why it matters: with the three roles decoupled, changing an implementation touches only the Provider — the interface and Consumer stay fixed. Move the shell from local to a remote sandbox and bash's model-visible schema is unchanged: invisible to the agent.
Three Practical Payoffs
1. Trimmable capability surface. Not every agent needs the network. Mount only bash + file read/write, omit web_search, and you get a more controllable, cheaper agent.
2. Swappable providers. The model backend is itself a seam. Point DEEPSEEK_BASE_URL from the official API to TeamoRouter — one env var, every other plugin untouched:
export DEEPSEEK_BASE_URL="https://api.teamorouter.com/v1"
export DEEPSEEK_API_KEY="sk-teamo-your-key"
3. Customizable tools. Want a tool that queries your internal ticketing system? Write a Cordis plugin, register it on ctx.tools, and the agent gains a tool — faster than waiting for official support.
A Minimal Mental Model
Think of dsh as a slot board:
[ bash ] [ files ] [ subagent ] [ web-search ] [ model-adapter ] ...
└────────── all mounted on the Cordis runtime ──────────┘
│
the agent's actual capability
You decide what's plugged in and what isn't. This model explains most of dsh's design decisions — why the default preset bundles bash + file read/write, why headless mode needs only env vars.
FAQ
What's the relationship between Cordis and dsh?
Cordis is the underlying plugin runtime (a standalone MIT project); dsh is the agent framework built on top. dsh's "everything is a plugin" is Cordis's "reversible, composable registrations" applied to agents.
Do I need to write Cordis plugins to use dsh?
No. Day-to-day use is install + set env vars. Writing plugins is the advanced skill you reach for only when extending dsh.
What's an "agent preset"?
A preset is a bundle of plugins. dsh's standard preset typically includes bash, file read/write, and glob/grep; custom presets can trim or extend it. It's how "trimmable capability" is delivered in practice.
Is a provider swap truly invisible?
To the agent's capability surface, yes — the tool schemas don't change. But different providers differ in model ability, price, and rate limits; those are model-layer differences, not framework-layer ones.
What's the direct value to me?
Two things: cheaper — plug a cheap model (DeepSeek V4) into dsh and the same agent loop costs an order of magnitude less; and control — you decide exactly what the agent can and can't touch.
To experience the architecture, get a key at TeamoRouter, point the model adapter at it, and leave every other dsh plugin untouched.