FAQ

This page answers common questions about DeepSeek Harness (dsh), organized by topic. If you don't find an answer here, check troubleshooting or ask the community.

Installation

What is npx? Do I need to install anything manually first?

npx is a command that ships with Node.js; it means "temporarily download an npm package and run it, leaving nothing installed behind". npx @deepseek-ai/dsh web fetches the dsh package from the npm registry and runs its web entry — no manual npm install needed. The first run also initializes the profile and downloads dependencies, so it is slow once; later runs reuse the cache. See installation.

How do I install Node.js on my system?

• Windows: download the LTS .msi from nodejs.org and double-click, or run winget install OpenJS.NodeJS.LTS;
• macOS: download the LTS .pkg from nodejs.org and double-click, or run brew install node@24;
• Linux: distribution packages are often outdated; prefer nvm (nvm install 24).

Reopen the terminal afterwards and verify with node --version that the version satisfies ^22.19 or >=24. Full steps: installation.

The terminal says 'npx' is not recognized — what now?

Node.js is not installed properly, or the terminal wasn't reopened after installing. Install Node.js as above, reopen the terminal, and retry; if it still fails, see the PATH-related entries in troubleshooting.

What Node version do I need?

^22.19 or >=24 is recommended, and required when running from source. Check with node --version before deciding whether to upgrade. See installation.

The first npx run is slow or seems stuck — what's wrong?

The first npx @deepseek-ai/dsh web initializes the web profile and downloads dependencies, so it needs network access and takes noticeably longer than later runs. Confirm your network and Node version are fine, then let the first download finish.

What's the difference between npx and running from source?

npx runs the published release and is the day-to-day path. Running from source needs git clone, pnpm install and pnpm run build, and suits following the latest development or contributing. Both share the same launch arguments.

Model configuration

Where do I enter my API key?

Open Settings → Models, enter your DeepSeek API key and save. Model routing takes effect immediately — no server restart needed. See configure models.

How do I connect other providers or custom endpoints?

On the models page, choose Add Provider for a catalog provider such as Anthropic or OpenAI, or Add Custom Provider to fill in any OpenAI-compatible Base URL and key. Installed catalogs supply endpoints, protocols and model lists; custom providers need you to fill in the provider ID, base URL, protocol, credentials and at least one model.

Where is the key stored? Is it safe?

Keys are write-only. After saving, the page only receives a masked descriptor; the plaintext key lives in $DSH_HOME/.credentials.yaml, and settings keep only its credential reference. Never commit keys or hardcode them in config files.

How do I configure a key for headless mode?

Headless mode reads configuration from environment variables: set DEEPSEEK_API_KEY, and DEEPSEEK_BASE_URL when you need a custom endpoint.

Workspaces

Why is the session input disabled?

Because no workspace is selected yet. Click Select Workspace, add the project directory where you launched dsh, and select it to enable input.

Which files can the agent access?

The agent's view is the workspace plus your description. By default it can only read and write files, and run commands, within the workspace directory. Set only the directory you need as the workspace — the tighter the boundary, the safer.

Approvals

Why do approval prompts appear?

Before sensitive actions such as writing files or running commands, if the current permission policy requires approval, the Web UI asks you first. This is your last line of defense: review the diff and command before approving.

How do I adjust the approval policy?

Permission presets bundle a sandbox mode with an approval policy into selectable levels, defaulting to workspace-write (workspace write + ask) and danger-full-access (full access + never ask). For daily use, keep a preset that asks.

Can I continue after rejecting an action?

Yes. After rejecting, ask the agent to explain first or to do analysis only, then keep going. If the same approval keeps firing, check whether the workspace scope is too broad or the task description is unclear.

Headless mode

What is headless mode?

Headless is a browser-less, one-shot mode: dsh --profile headless "task" runs one fresh persisted session, prints the final answer, and exits. It suits scripted calls and CI integration.

What does headless mode need?

A model API key provided through environment variables (DEEPSEEK_API_KEY, optionally DEEPSEEK_BASE_URL). Without a key, tasks fail or are skipped.

Plugin install

How do I install a plugin into a profile?

Use dsh plugin --profile <name> <pnpm args>, which forwards to pnpm inside the profile directory. First use initializes that profile. See CLI & profiles.

Where do I discover plugins?

Add the dsh-plugin topic to your plugin repository, or browse community plugins on the GitHub dsh-plugin topic. See ecosystem.

Common errors

I see MISSING_CREDENTIAL

A credential is missing. Store the provider key through the models page, or provide the referenced environment variable.

I see UNKNOWN_MODEL

The model is unknown. Select a configured model, or add the missing model to your custom provider.

"Fetch available models" returns 401

The key is wrong or unauthorized. Model discovery calls the OpenAI-compatible GET /models endpoint; if the service does not offer it, enter models manually.

The port is already in use

Pick another port: dsh --profile web --port 8080 (--port belongs to the web app). If that still fails, free the process occupying the port — see troubleshooting.