@deepseek-ai/dzcf

English | 中文

dzcf (DeepSeek Zero-Config Flow) is the one-command setup wizard for DeepSeek Harness. It takes a machine from nothing to a runnable dsh deployment: installs the dsh CLI when missing, stores the DeepSeek API key (and optional endpoint override) in the harness-home credentials document, and proves the chosen profile composes.

Quick start

npx @deepseek-ai/dzcf            # install-and-run through npx; interactive: install, key, base URL, surface
npx @deepseek-ai/dzcf i          # same full init, explicitly
dzcf --help                      # grammar (after a global install)

Non-interactive (CI, scripts):

dzcf i --key sk-… --mode headless --yes
dzcf i --key sk-… --mode web --base-url https://relay.example.com --yes
dzcf i --key sk-… --mode web --dry-run    # report the plan, write nothing

What it does

1. Detects dsh (dsh -V). Missing? The wizard offers to install @deepseek-ai/dsh globally through pnpm or npm (--yes skips the question; a run without a package manager fails loud).
2. Collects inputs — the DeepSeek API key (masked prompt), an optional DEEPSEEK_BASE_URL override, and the runtime surface (headless one-shot CLI or web browser UI). Interactive mode asks; non-interactive mode requires --key and --mode and fails loud otherwise.
3. Stores credentials in $DSH_HOME/.credentials.yaml — the managed, owner-only (0600 under 0700) document that dsh-credentials-local reads. Existing untouched entries survive; writes re-read under the cross-process writer lock and commit atomically. Keys are never echoed: the summary masks them (sk-***4321).
4. Verifies the profile with dsh --profile <mode> --dump-default-config — the shipped web/headless profiles auto-initialize on first boot, so a successful dump proves the zero-config loop without a model call. Failures report the dsh stderr; the stored credentials remain.
5. Prints next steps — dsh web or dsh --profile headless "your task".

Nothing else is touched: no profile files are rewritten, no cordis.yml is generated, and the wizard itself never calls a model API.

Options

Option	Meaning
i	Full init (same as the bare command).
c	Configure integrations only; requires --profile and --with.
k	Update credentials only (key / base URL).
-k, --key <key>	API key; skip the masked prompt.
--base-url <url>	Endpoint override; any http(s) URL, else exit 1.
-m, --mode <mode>	headless or web; skip the list prompt.
-l, --lang <lang>	Interface language: zh-CN (default) or en.
-y, --yes	Assume yes for the install and write confirmations.
-p, --profile <name>	Custom profile name for integration options.
--with <list>	Integration ids, comma-separated (exa,terminal,lsp).
--mcp-command <cmd>	MCP server launch command (non-interactive --with mcp).
--dry-run	Print the planned writes and verify command, touch nothing.
-V, --version	Print the version and exit.

Integration options

The wizard can extend a deployment with capabilities beyond the shipped web/headless surfaces. Selecting any option creates a custom profile (--profile <name>, default dzcf) and installs the capability through the launcher's own dsh plugin add, then writes its patch rows and verifies the composition:

Option	Effect
exa	Register the Exa search provider (EXA_API_KEY → $DSH_HOME/.env).
perplexity	Register the Perplexity search provider (PERPLEXITY_API_KEY → $DSH_HOME/.env).
sqlite	Persist session history in SQLite (replaces the JSONL default).
terminal	Add the persistent PTY terminal tool.
lsp	Add language-server symbol navigation (service + stdio backend + tool).
codex	Delegate subtasks to a local Codex CLI (requires codex installed).
claude	Delegate subtasks to a local Claude Code (requires claude installed).
mcp	Attach one MCP server (enter its launch command).

Interactive mode asks a multiselect; non-interactive uses --with exa,terminal,lsp and --profile <name>. Provider keys are prompted only in interactive mode.

Exit codes: 0 success or user cancellation, 1 any failure (missing dsh/package manager/key/mode, malformed credential document, failed install, failed verification).

Development

The wizard is a menu-driven CLI (ASCII banner + three flows) over three injectable seams — RunFn (subprocesses), PromptFn (@clack/prompts port), and the harness home — so the whole flow is testable without a TTY. The package is self-contained: the two small filesystem utilities it reuses are vendored under src/lib/, so it builds, publishes, and npx-runs with only public npm dependencies. Source launch: pnpm dev <args...>; build with pnpm build; test with pnpm test.

Known limitations

• The base-URL prompt accepts any http(s) URL; reachability and key validity are not checked — the first real request owns that failure.
• Credential writes are atomic but not crash-durable; the document is re-read on every boot.
• On Windows the 0600/0700 permission checks are skipped, matching dsh-credentials-local.
• The integration dsh plugin add step requires the target capability packages to be published on npm.