Port 3080 is taken and DSH won't start. What do I do?

Start on another port: dsh --profile web --port 8080. --port is a web-app argument that goes after the profile.

Why doesn't my DSH plugin load after installing?

Check the plugin's compatible DSH version first. Then see if a git-hosted plugin was blocked by allowBuilds — add the allow key to the profile's pnpm-workspace.yaml and reinstall.

How do I fix a DSH model that won't connect?

In Settings → Models, confirm the API key is saved; the model route takes effect immediately. Custom endpoints use OpenAI-compatible config — see the official providers doc.

Where do I inspect DSH configuration?

Run dsh --dump-config for the composed config tree and dsh --dump-default-config for defaults. Config files live under $DSH_HOME.

Where is DSH session data stored?

Sessions live at ~/.dsh/sessions/ / /session.jsonl. Back this up before debugging or recovery.

DSH troubleshooting: port in use and plugins not loading

DSH beginners most often get stuck on four things: port 3080 in use, plugins that don't load, models that won't connect, and a Web UI that won't open. Each has a straightforward fix.

Port 3080 is taken (DSH won't start)

If the default port is busy, start on another one. --port is a web-app argument and goes after the profile:

bash

dsh --profile web --port 8080

dsh web is an alias for --profile web, and the Web UI opens at http://127.0.0.1:3080 by default (source). Watch the access URL printed at startup so you don't use the wrong port.

A DSH plugin installs but doesn't load

If a plugin doesn't take effect, check the compatible version first, then build-script approval. Troubleshoot in order:

Check the DSH version the plugin declares. DSH is in developer preview (currently 0.1.0-rc.6), and version mismatches can fail silently.
Git-hosted DSH plugins may be blocked by pnpm's allowBuilds on first install — copy the allow key from the error into the profile's pnpm-workspace.yaml and run add again.
Make sure you copied the full install command, e.g. dsh plugin --profile web add github:ccch1mneyyy/dsh-tui (source).

The fastest way to confirm whether a plugin actually loaded is to run dsh --dump-config — check there first before editing config or reinstalling.

The DSH model won't connect

A dead model connection is usually a misconfigured API key. Open Settings → Models in the Web UI, enter your DeepSeek API key and save — the model route is available immediately without restarting (source). For custom endpoints, use an OpenAI-compatible config; see the official providers doc.

Once the model is set, the normal flow is: select a workspace → enter a task → the agent starts working. Agents can read and edit workspace files, run commands, delegate work, and maintain a plan; when an operation needs approval under the current permission policy, the Web UI asks you first and waits for your confirmation. So if a task looks "stuck," check whether it's waiting for approval before killing the process.

Blank DSH Web UI

For a blank page, first confirm the process is running and the address is right. Then check the workspace: a fresh Web UI selects no workspace until you add one. Click Select workspace, add the project directory, and only then does the session input become usable (source). The full first-run flow is: Settings → Models (enter your API key) → Select workspace → run a task → return to saved sessions anytime to keep using DSH. Missing any step makes the UI look "broken." Also double-check the URL is http://127.0.0.1:3080 — don't keep hitting an old port.

Inspecting DSH config and data

When you suspect config or data issues, inspect with commands before touching files. Run dsh --dump-config to see the composed config tree, or dsh --dump-default-config for defaults — both inspect the tree directly without booting DSH (source). Session data lives at ~/.dsh/sessions/<project>/<session>/session.jsonl — back it up before debugging. If those commands look right, the problem is usually in the workspace or permissions; watch for permission prompts in the Web UI.

If the Web UI won't open at all and a task can't wait, go headless instead: run dsh --profile headless "your task" — DSH starts one fresh session, prints the final answer to the terminal, and exits, with no browser involved (source). If you're still stuck, review How to install a DSH plugin or find your plugin's docs on dsh-plugin.org.

Source: official Quickstart, dsh CLI README