FAQ

Every pitfall beginners hit, in one place: npx stalls, port conflicts, MISSING_CREDENTIAL, plugins that seem dead after install, migrating data — grouped for quick lookup.

7 min read

How to use this page

These are the pitfalls new users hit most often, grouped into four categories: install, model, plugins, and misc. Find your symptom first; if it's not here, ask in the official DSH Discussions — the community is quick to respond.

Installing

node -v prints a version, but npx still fails?

Two usual suspects:

  • Version below 22: DSH requires Node.js 22 or newer. Install the latest LTS from nodejs.org and reopen the terminal;
  • command not found: npx: Node.js isn't installed properly or isn't on PATH. Open a fresh terminal window; on Windows use "PowerShell", not the legacy "Command Prompt".

npx download is painfully slow or stalls?

That's the network. Point npm at a faster registry (one-time setup):

npm config set registry https://registry.npmmirror.com

Then retry npx @deepseek-ai/dsh web.

Browser says 127.0.0.1:3080 is unreachable?

Check in order:

  1. Is the terminal running dsh still open? Closing it stops the service;
  2. Any red errors in that terminal? Fix those first;
  3. Port already taken? Start on another one: dsh web --port 3081, then browse to 127.0.0.1:3081.

Is the antivirus alert normal?

Yes. dsh opens a local port to serve its web UI, and some antivirus tools ask about it. Choose "allow" — DSH listens only on the local loopback interface and exposes nothing to the outside.

Models

What about MISSING_CREDENTIAL?

That means no API key was provided. Open Settings → Models, paste the key into the DeepSeek card, and save. No restart needed — just resend your message.

401 or "insufficient balance"?

  • 401: the key was copied wrong or was revoked. Copy it again from the platform, watching for stray spaces;
  • Insufficient balance: the DeepSeek API is prepaid — top up at platform.deepseek.com and retry.

Can I use the free quota from the web chat?

No. The DeepSeek web chat and the open-platform API are separate systems: the former lives on chat.deepseek.com, the latter is billed per token and needs a balance. DSH uses the API. Prices are low, though — light use typically costs pocket change per month.

Can I use another vendor's models?

Absolutely — DSH is model-agnostic. Settings → Models → Add provider (pick a vendor) or add a custom provider (OpenAI-compatible base URL + key). See the model configuration tutorial.

Plugins

Installed a plugin but nothing happened?

Nine times out of ten you forgot to restart. After installing, uninstalling, or upgrading a plugin you must stop dsh (Ctrl + C) and start it again (dsh web) for it to load. Refresh the browser page too.

Install fails with a prepare / allowBuilds error?

That's pnpm's safety mechanism refusing to run an unfamiliar package's build scripts. The fix (details in the install plugins tutorial):

  1. Open ~/.dsh/profiles/web/pnpm-workspace.yaml;
  2. Add the package name under allowBuilds as the error suggests;
  3. Re-run the install command.

Grant this only to plugins you trust.

Plugins conflict — now what?

Symptoms are usually a broken feature or a startup error. Debug order:

  1. Recall what you installed most recently and uninstall it first;
  2. Still broken? Reset the profile (next item);
  3. Before resetting, save the output of dsh plugin --profile web ls so you can reinstall selectively later.

How do I wipe all plugins and start over?

# Quit dsh first, then:
rm -rf ~/.dsh/profiles/web

The next dsh web rebuilds a clean web profile. Your API key lives in ~/.dsh/.credentials.yaml, which is untouched — no need to re-enter it.

Misc

Where are my conversations stored? Can I move them to another computer?

Everything lives in ~/.dsh (C:\Users\<you>\.dsh on Windows). Copy the whole directory to the same location on the new machine and your logs, settings, and keys come along. Quit dsh before migrating.

Is DSH free?

The software itself is MIT-licensed open source and entirely free. The only cost is model API usage, billed by volume.

How does it relate to Claude Code, Codex, and the like?

They're all "AI coding agents" in the same broad category. DSH's distinguishing feature is the everything-is-a-plugin architecture — models, tools, and UI are all swappable, so you assemble your own assistant instead of accepting a vendor's sealed box. If you like tinkering and want full control of your AI toolchain, DSH is worth a try.

Where do I report bugs and exchange tips?

Tutorial index

All tutorials