The examples/ directory holds the runnable demo leaves — thin cordis.yml compositions — while packages/examples/ holds the reusable demo bundles those leaves load. Together they are the shortest path from "install dsh" to "a real agent acting against a real model," and they double as the substrate for the keyless acp-snapshot and real-API e2e test suites. This page maps every example, how to run it, and what it demonstrates.

The two layers

examples/AGENTS.md is explicit: examples/ is one workspace member and the module-resolution root for runnable and test Cordis configs, but it is not a build target. Its root examples/package.json (the dsh-examples umbrella) declares the union of every leaf's cordis.yml plugins as workspace:* deps, so a plain-Node (:lib) boot of any leaf resolves its plugins through real package exports → lib. Each leaf's own package.json is metadata only (name, description) with no scripts.

packages/examples/README.md adds the balance: the -demo npm suffix marks each bundle as non-product surface. agent-spine-demo is the shared spine; acp-demo adds an automation entry point; jsonrpc-demo boots a deployment-owned plugin tree. Product one-shot execution belongs to dsh --profile headless; no bundle here provides it.

The demo leaves (examples/)

Leaf	Purpose	What it demonstrates
acp-agent/	An ACP automation server over JSON-RPC stdio	Agent Client Protocol, Code Mode, subagents, sandboxing
headless-agent/	One complete headless coding-agent turn	DeepSeek V4 + bash/fs tools, subagents, workflows, Ralph, todo_write, JSONL persistence
jsonrpc-agent/	Unattended JSON-RPC coding-agent composition	The Python SDK's bundled JSON-RPC runtime
mcp-memory/	Three default-off third-party memory MCP reference configs	MCP client interoperability (Memorix, MCP Reference Memory, Engram)
web-cordis/	Self-referential Cordis tool demo	dsh-tool-cordis: the agent inspects/mounts plugins in-process
web-schedule/	Session-local Schedule overlay	schedule_create/list/delete, time-context reminders

acp-agent

Automation-oriented Agent Client Protocol server for parent agents / subagent providers. Run it (both need DEEPSEEK_API_KEY from repo-root .env):

pnpm run demo:acp      # JSON-RPC stdio ACP
pnpm run demo:code-mode # same protocol with Code Mode tool transport

Stdout stays protocol-pure (newline-delimited ACP JSON-RPC); diagnostics go to stderr. Each session/new gets a session-scoped cwd, and DSH_PERMISSION_MODE selects workspace-write vs danger-full-access. This is the primary ACP snapshot-test example (examples/acp-agent/tests/snapshots/).

headless-agent

The keyless/real-model replay composition for a headless coding agent. Run via the product command:

pnpm dsh --profile headless "fix the failing test in this workspace"

It explicitly mounts the shared agent spine, one root agent, persistence, and checkpoint policy. Its snapshot suites drive the config through tests/fixtures/headless-driver.ts, which emits canonical session events as JSONL. e2b.cordis.yml swaps local filesystem/subprocess for one shared E2B sandbox (E2B_API_KEY), a provider-composition POC.

jsonrpc-agent

The unattended composition for the Python SDK's bundled JSON-RPC runtime — no terminal UI, logger, approval UI, or user-questions tool, because stdout belongs to the SDK protocol. Tools: foreground bash, read/write/edit, subagent (one in-process spawn provider), todo_write. Runtime env: DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, DSH_CWD, DSH_SESSION_ROOT, DSH_SYSTEM_PROMPT. The bundled executable carries every named plugin, so the target machine needs no Node.js. The minimal.cordis.yml variant (persistent PTY + str_replace_editor) is the complete standalone counterpart of the Web minimal preset; minimal.py runs it through the Python SDK. Run it demo with demo:acp-style bin via the jsonrpc-demo bundle.

mcp-memory

Three default-off reference configs connecting one external memory system through @deepseek-ai/dsh-mcp-client. Pick one with --patch:

dsh web --patch "$PWD/examples/mcp-memory/memorix.cordis.yml"
# or mcp-reference-memory.cordis.yml, or engram.cordis.yml

DSH starts the stdio child / connects the HTTP server, discovers MCP tools, and exposes them as mcp__<serverName>__<tool>. It does not install, initialize, or supervise the third-party server. Tested pins: memorix@1.3.0, @modelcontextprotocol/server-memory@2026.7.4, engram@v1.20.0. Byte-for-byte reproducibility is exactly what the snapshots demand.

web-cordis

Self-referential demonstration of @deepseek-ai/dsh-tool-cordis: the agent can inspect its running Cordis process and mount/unmount model-authored plugins in memory (temporary plugins vanish on unmount or exit).

pnpm run demo:cordis      # browser interface
pnpm run demo:cordis acp  # ACP automation server instead

web-schedule

Opts one dsh web process into session-local schedule reminders:

dsh web --patch examples/web-schedule/cordis.yml

The model uses schedule_create/schedule_list/schedule_delete; the browser attaches its IANA zone to each prompt and time-context interprets unqualified dates in that zone. Reminders are owned by the originating Session log; closing the process stops the in-memory timer without deleting the record, and reopening the Session restores the wait.

The reusable bundles (packages/examples/)

Package	npm name (version)	Role / bin
agent-spine-demo/	@deepseek-ai/dsh-agent-spine-demo	Default executor-less/UI-less agent spine bundle (no bin)
acp-demo/	@deepseek-ai/dsh-acp-demo	ACP automation server app; bin dsh-acp-demo
jsonrpc-demo/	@deepseek-ai/dsh-sdk-jsonrpc-demo	Boots an external Cordis config for the stdio JSON-RPC SDK runtime; bin dsh-jsonrpc-agent

agent-spine-demo: the "spine"

The spine is the shared, executor-less, UI-less agent bundle — the common services, background-job registry and controls, optional persisted goals, the concrete agent loop, local skill and agent-instructions providers, and model-facing shell/skill consumers. Deployments still choose the LLM adapter, bash executor, and presentation. It mounts dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-skill + dsh-skill-filesystem, dsh-agent, dsh-goal + dsh-goal-round-driver, dsh-jobs-local, dsh-invariants (with the four core companions dsh-session/dsh-agent/dsh-scope/dsh-agent-loop invariant), dsh-agent-loop, and dsh-llm-retry — plus dsh-tool-bash, dsh-tool-skill, dsh-tool-jobs, and workspace context via dsh-agent-instructions.

// packages/examples/agent-spine-demo/src/index.ts (excerpt)
export const name = 'agent-spine-demo'
// …imports Timer, LlmRuntime, SessionStore, SessionTitleService, SystemPrompt,
// ToolRuntime, SkillRegistry, AgentRegistry, GoalService, LocalJobRegistry,
// InvariantRegistry + invariant companions, AgentLoop, llmRetry, …

The plugin intentionally exposes named exports only — Loader default unwrapping would discard its Config schema (documented in docs/postmortem/0001-acp-default-export-drops-inject.md).

How to run each

examples/ leaves carry no scripts; the run commands are root package.json scripts:

"demo:acp":   "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
"demo:cordis":"node scripts/demo-cordis.mjs",
"demo:code-mode":"node scripts/demo-code-mode.mjs",
"mock:llm":   "node --import tsx packages/test-support/llm-mock-server/src/bin.ts"

• demo:acp boots the ACP bundle against examples/acp-agent/cordis.yml.
• demo:cordis runs the browser Cordis-tool demo by default; pnpm run demo:cordis acp selects the ACP variant.
• demo:code-mode runs the ACP protocol with the Code Mode tool transport.
• mock:llm starts the scriptable LLM fault server for local recovery tests.

Every example ships both keyless and with-key smokes (per examples/AGENTS.md): keyless boots the real cordis.yml through the Loader and asserts output + clean exit; with-key sends a live-model prompt and verifies external state, self-skipping without DEEPSEEK_API_KEY.

Version table

Further reading

• Testing strategy — the ACP snapshot suite (dsh-acp-snapshot) that drives examples/acp-agent.
• Vendored libraries — the Cordis framework every cordis.yml loads.
• examples/AGENTS.md — the example-facing contribution and test conventions.
• packages/examples/README.md — the bundle/leaf split and -demo naming contract.
• packages/examples/agent-spine-demo/README.md — the spine bundle's configuration surface.
• docs/postmortem/0001-acp-default-export-drops-inject.md — why the spine uses named exports.