Configuration Reference
Curated lookup of the DeepSeek Harness settings, credentials, environment variables, model routes, sandbox modes, and persistence options users and plugin authors touch most
This page curates the configuration entries users and plugin developers look up most often. The exhaustive source is the generated config catalog — regenerated from source and shipped with a reviewed Chinese counterpart — so treat this page as a fast lookup, not the authority. Each entry lists the key, where it lives (environment variable, cordis.yml, a settings file, or a CLI flag), and the default the catalog records; required keys with no catalogued default are marked accordingly.
Settings & credentials
settings.yaml — @deepseek-ai/dsh-settings-file
The user-settings document. Keys path (defaults to settings.yaml under the harness home), dshHome (defaults to $DSH_HOME or ~/.dsh), watch (defaults to true), and debounceMs (defaults to 100) all live in the plugin's cordis.yml config: block. See CLI & Profiles.
.credentials.yaml — @deepseek-ai/dsh-credentials-local
The credentials reference document, shaped like settings: path (defaults to .credentials.yaml under the harness home), dshHome ($DSH_HOME or ~/.dsh), watch (true), debounceMs (100). Keep secrets out of cordis.yml; see Security.
Environment variables
| Variable | Set by / read by | Purpose |
|---|---|---|
DEEPSEEK_API_KEY | @deepseek-ai/dsh-llm-deepseek (apiKeyEnv), @deepseek-ai/dsh-web-search-deepseek | DeepSeek API key, resolved per request. |
DEEPSEEK_BASE_URL | @deepseek-ai/dsh-llm-deepseek (baseURL fallback) | Endpoint base; falls back to the public API. |
DSH_HOME | harness home resolution | Harness home directory; defaults to ~/.dsh. |
DSH_AGENTS_HOME | @deepseek-ai/dsh-skill-filesystem (agentsHome) | Shared agent config root; defaults to ~/.agents. |
DSH_BUNDLED_SKILL_DIR | @deepseek-ai/dsh-skill-filesystem (bundledSkillDir) | Bundled skill root, mounted when default roots are included. |
E2B_API_KEY | @deepseek-ai/dsh-e2b (apiKey) | E2B sandbox API key; never forwarded into the sandbox. |
EXA_API_KEY | @deepseek-ai/dsh-web-search-exa | Exa search key; empty leaves the provider unavailable. |
PERPLEXITY_API_KEY | @deepseek-ai/dsh-web-search-perplexity | Perplexity search key; empty leaves the provider unavailable. |
DSH_WEB_URL | exposed by @deepseek-ai/dsh-web-app (surfaceContext) | Bash variable carrying the web surface URL. |
DSH_CORDIS_CONFIG | @deepseek-ai/dsh-subagent-dsh-sdk (env) | Names a child runtime's cordis.yml path. |
Model & provider routes
@deepseek-ai/dsh-agent-default-model
Composition entry for the default model selection. provider (registered provider route) and model (provider-owned model id) are both required — no catalogued default. See Configure models.
@deepseek-ai/dsh-llm-deepseek
The direct DeepSeek provider. apiKeyEnv defaults to DEEPSEEK_API_KEY; baseURL falls back to $DEEPSEEK_BASE_URL then the public API; thinking is enabled/disabled; reasoningEffort is off/high/max (defaults to high); maxTokens defaults to 256,000; defaultContextWindow defaults to 1,000,000; models is an advisory catalog (defaults to V4 Flash and V4 Pro). The same shape doubles as the llm-deepseek settings section. See Configure models.
@deepseek-ai/dsh-llm-pi-ai
Custom OpenAI-compatible provider routes, keyed by provider. Each providers entry takes apiKeyEnv, baseURL, api (the wire protocol, e.g. openai-completions), models, modelOverrides, defaultContextWindow (defaults to 262,144), and defaultMaxTokens (defaults to 32,768). See Configure models.
Permission presets & sandbox modes
@deepseek-ai/dsh-permission-presets
The preset table and composition default. presets defaults to workspace-write (workspace-write + ask) and danger-full-access (danger-full-access + never); defaultPreset picks the preset new sessions start from. custom is reserved. See Security.
@deepseek-ai/dsh-sandbox-policy
The deployment's shared sandbox default. mode defaults to read-only; workspaceRoot defaults to process.cwd() and is the fallback root for agentless calls and sessions without a cwd. See Security.
@deepseek-ai/dsh-user-approval
The default approval policy. policy is ask (the default) or never; never auto-rejects every ask deterministically for CI and unattended runs. See Security.
Profiles, presets & patch layers
@deepseek-ai/dsh-agent-presets
Where presets live and which one is default. default (required — missing fails loud at mount), roots (scanned preset directories in precedence order), and includeUserRoot (append the harness home's user preset dir). See Agent Presets and CLI & Profiles.
@deepseek-ai/dsh-cordis-host-runner
The runner behind dynamic Cordis plugins. vmTimeoutMs caps synchronous VM evaluation time. See the Cordis primer.
Filesystem
@deepseek-ai/dsh-fs-local
The local filesystem backend. cwd defaults to process.cwd(); diffBasisMaxBytes caps each overwrite-diff side (defaults to 10 MiB). See CLI & Profiles for the workspace root.
Web UI
@deepseek-ai/dsh-host-webserver
The gateway's listen address. host is 127.0.0.1 or 0.0.0.0; port requests an OS-assigned port when 0. The web profile's --host/--port flags land here; the default serve is http://127.0.0.1:3080. See CLI & Profiles.
@deepseek-ai/dsh-client-connection
Non-loopback serving authorities. trustedHosts lists host:port (or port-less host) authorities the /api trust fence accepts beyond loopback; maxRequestBodyBytes caps each /api JSON body. The --trusted-host flag feeds these. See CLI & Profiles.
@deepseek-ai/dsh-web-app
Composed deployment settings plus per-invocation values: printUrl, surfaceContext (registers the app:web-surface prompt section and the DSH_WEB_URL variable), and trustedHosts from --trusted-host. See CLI & Profiles.
Sessions & persistence
@deepseek-ai/dsh-session-persistence-jsonl
The JSONL session-log backend. root is required (no default); packChunks defaults to true; compression defaults to checksummed Zstandard (zstd) frames. See Glossary.
@deepseek-ai/dsh-session-persistence-sqlite
The SQLite session backend. path is required (:memory: for tests); journalMode defaults to wal, with rollback-journal modes for network mounts. See Glossary.