@deepseek-ai/dsh-base

---

description: "The shared dsh core: model access, tools, durable sessions, and safety defaults for every dsh --profile surface, for users composing or customizing a profile." kind: "package-bundle"

@deepseek-ai/dsh-base

English | 中文

Summary

Every base-backed dsh --profile surface runs on dsh-base, so those surfaces share a model connection, the full tool set, durable session history, and workspace safety defaults. The shipped sdk-minimal profile deliberately uses a complete standalone tree instead. You rarely touch this bundle directly — shipped base-backed profiles already include it, and a custom base-backed profile names it first. When you need different defaults, change your profile patch or add a later bundle; this package is not a library you import.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

Use this package

The shipped web and headless profiles include the core; a custom profile names it as its first bundle. Configure model access and install Chromium before using browser search or page reading.

A minimal custom profile

To build a profile on the shared core, create a profile with a package.json that names @deepseek-ai/dsh-base first:

{
  "name": "my-profile",
  "private": true,
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base"]
    }
  }
}

Run dsh --profile my-profile "your task" and you get a working agent with model access, tools, persistence, and the default permission policy. The shipped web and headless profiles are created for you on first use. To add more bundles, run dsh plugin --profile add ; in-box bundles resolve from the dsh installation. The profile contract is documented in the app-boot profile section.

What you get

Out of the box, every profile built on this core provides: a DeepSeek model connection (the provider and model are configurable, and you can enable extra providers from your settings), the full tool set — file editing, shell commands, web search, subagents, an agent team with a shared task board, task and goal tracking — durable sessions that survive restarts, and the default permission policy that confines file writes to your workspace and asks before risky actions. Telemetry stays off unless you opt in.

Ordinary subagent and subagent_fork calls finish once. They wait for results by default; run_in_background: true returns a job collected through job_output or stopped through job_kill. Use spawn_teammate for named, persistent conversations controlled by Team messaging, follow-up, roster, and interruption tools.

Install the browser for search and page reading

web_search reads Bing results through Playwright Chromium without a search API key. web_fetch reads rendered pages through the same browser provider. Playwright requires a separate browser download; without it both tools fail with WEB_PROVIDER_CONFIGURED_UNAVAILABLE. From this repository, install it once per host:

node packages/web/web-fetch-playwright/node_modules/playwright/cli.js install chromium

Startup and launch errors name the installation's browser command. Plugins settings selects search and fetch providers independently; browser requests share the Browser search and fetch settings. DeepSeek, Exa, and Perplexity search APIs require their own credentials. fetchProvider: http selects unrendered HTTP page reading. Browser search reports challenges and blocked pages as errors.

Shell tools per platform

On macOS and Linux you get the bash shell tools; on Windows you get the PowerShell twins instead, so exactly one shell stack is available per machine. The safety behavior is identical on every platform. A Windows host that prefers the unconfined PowerShell executor can switch the shell rows in its profile patch — the switch must disable both PowerShell rows and re-enable both bash rows, otherwise the profile fails to load.

Changing the defaults

To change what a profile built on this core provides — a different default model, a stricter permission mode, extra or fewer tools — edit your profile's cordis.patch.yml or add a later bundle. Each patch entry replaces the target's whole configuration, so restate every setting you want to keep. Keep the sandboxed filesystem provider as the single file-write path: adding the plain filesystem provider on top of it makes the profile fail to load.

---

Understand the implementation

Implementation internals — click to expand

The bundle is a static patch document: one insert list applied over the empty profile root. It mounts no service, emits no events, and holds no mutable state; each inserted row's package owns that row's behavior and invariants.

Composition mechanics

A patch replaces the targeted row's whole config rather than merging into it. Later bundle layers and the user's profile cordis.patch.yml override rows by id, with the last write winning per row. Rows whose value differs by mode do not live here: each mode bundle restates its complete configuration, keeping any single row down to one bundle layer plus the user's. The full row set and its rationale are documented inline in cordis.patch.yml; the generated composition graph renders it.

Platform gating

The patch gates the two executors by platform on its own rows — bash-sandbox carries disabled: !!js process.platform === 'win32' and its twin pwsh-sandbox mounts on win32 only with the inverted expression — and the single tool-shell row reads the same platform fact into its dialect config, so the model-facing tool name always matches the executor that mounted. The permission surface stays identical to POSIX: the sandbox policy executes the same file-effect policy through the Windows ACL restricted-token runner (dsh-sandbox-local → @deepseek-ai/dsh-sandbox-windows-acl), and fs-sandbox keeps fencing ctx.fs writes — mounting dsh-fs-local alongside it would double-register ctx.fs and fail the load.

Source map

File	Role
cordis.patch.yml	The bundle substance: the base plugin rows, with per-row rationale as inline comments
src/index.ts	Package entry; carries no runtime API
src/invariant.ts	Invariant companion: no runtime invariant; each inserted row's package owns its invariants
tests/base.spec.ts	Manifest declaration and platform-gating checks

Invariant ownership

The invariant companion registers an empty installer because the package is a static patch-list carrier: each inserted row's own package carries that row's invariants, and the bundle owns no mutable relation to check.

---

Further Exploration

Read these pages when you want to go deeper into profiles, the surfaces built on this core, or the exact composition.

• app-boot profile section — how profiles are resolved, layered, and customized.
• Bundle package map — the surfaces built on this core.
• Generated composition graph — the exact plugin set each shipped profile uses.
• Profile plugin bundles note — the profile and bundle composition design.
• Codex and Claude Code provider bundles — optional provider bundles you can install on top.

---

Model Experience

Indirectly, through each inserted row's package, which owns that row's model-facing behavior.

KV Cache effect

The bundle itself adds no request prefix; each inserted row's package owns any cache effect.

Known Limitations and Deferred Work

These limits tell you when the core needs extra care or where an override must go. They are current package constraints, not a general comparison or a task backlog.

• Overrides replace whole settings blocks — a patch entry replaces the target's entire configuration, so your override must restate every setting you want to keep; nothing merges automatically.
• Per-surface settings belong to the surface's bundle — a default that differs between the web GUI and headless mode lives in that surface's bundle, not in the shared core.
• Windows temp grants are private per-session subdirectories — workspace-write confines writes to the workspace plus the session's own temp subdirectory (\dsh-, TMP/TEMP rewritten for confined children); read-only grants nothing. See @deepseek-ai/dsh-sandbox-windows-acl.
• Adding the plain filesystem provider on top of the sandboxed one fails the profile — the two register the same service, so the profile refuses to load; use one or the other.
• Browser installation is required — default search and fetch use Playwright Chromium. Without its browser download, both fail with WEB_PROVIDER_CONFIGURED_UNAVAILABLE; choose another provider explicitly if Chromium cannot run on the host.

Dev Note

Working context for maintainers — click to expand

None.