Fix DeepSeek Harness Model Connection: API Key & Proxy

When a DeepSeek Harness model fails to connect, nine times out of ten the API key or endpoint is wrong: check the key and endpoint in settings first, then the network proxy, then whether the local model service is running.

Overview

The model chain has three segments: config, network, and model service. Config means the API key and endpoint, network means proxy and timeouts, and model service means the cloud API or the local model process. Debug in that order, and most issues are solved at the first step. Read the error while you debug: 401/403 point to the key or quota, timeout errors point to network or proxy, and 404 usually means a wrong model name — the error already narrows down the scope for you. DSH is still in developer preview and config items may change — follow the official docs (source).

DeepSeek Harness API key and endpoint config

When the model does not connect, nine times out of ten the API key is not configured properly. Open Settings → Models in the Web UI, enter your DeepSeek API key and save — the model route takes effect immediately without a restart (source). A wrong key or exhausted quota looks the same as a connection failure: 401 Unauthorized or 403 means the key is invalid or lacks permission, while 402/429 usually means insufficient balance or rate limiting — the error tells you whether it is a key or a quota problem. When copying the key, avoid trailing spaces or extra characters, and note that a newly issued key usually takes seconds to a few minutes to take effect. If the Web UI itself will not open, fix the UI first before investigating the model — see Fix Blank DeepSeek Harness Web UI.

If the key was working before and suddenly stops, check the quota page first — usage-based APIs revoke access at the balance limit, and the error code switches from 401 to 402/429 around that point. Also verify you saved the key in the profile actually in use (web vs headless), since the two profiles can carry different model configs.

For a custom endpoint (for example a third-party OpenAI-compatible API), fill in the Base URL and the model name on the same page — the two must match; see the official providers docs. If you suspect the config was not written, run:

dsh --dump-config

and check whether the model rows appear in the merged config tree (source).

DeepSeek Harness model network proxy and timeout

If the key is fine but the model still fails, check the network next. Three common causes: timeouts (slow model responses, unstable proxy), a proxy that does not apply to the DSH service process, or a firewall blocking outbound connections. First confirm the model API domain is reachable with curl:

curl -I -m 10 https://api.deepseek.com

-m 10 caps the request at 10 seconds so the command cannot hang. A 200 or 30x response means the network is fine; spinning forever or a timeout points to the network or proxy. Inspect the current proxy variables with env | grep -i proxy (or $env:HTTP_PROXY on Windows) and confirm the DSH service process started with the same proxy inherited — proxy environment variables do not affect already-started processes, so restart DSH after changing the proxy. If timeouts are frequent, raise the timeout and retry settings in the model config; full proxy setup steps are in Speed up DSH plugin downloads with a mirror or proxy.

If curl reaches the API but DSH still times out, check DNS separately (dig api.deepseek.com or nslookup): a stale or wrong DNS entry can make the service resolve slowly while the browser, with its own cache, works fine. Flushing the system DNS cache or switching the resolver usually clears it.

DSH plugin local model access (LM-Kit / llama.cpp / Ollama)

When a local model fails to connect, the service is usually not running or the endpoint is wrong. The three common local model services all expose OpenAI-compatible endpoints, so DSH connects through the generic config:

1. LM-Kit: a local OpenAI-compatible service — point the endpoint at its /v1 local address (port per your launch config).
2. llama.cpp (llama-server): default http://127.0.0.1:8080/v1.
3. Ollama: default http://127.0.0.1:11434/v1.

Debug order: curl the /v1 address to confirm the service is up → check the port and that the model name matches a loaded model → confirm the model finished loading before retrying. A wrong model name returns a direct 404. Three concrete checks:

1. Is the service running? curl the corresponding /v1 address; if it fails, confirm the process was not killed — an unlistened or broken local port shows up as request failures.
2. Is the port right? llama-server and Ollama let you change the default port at launch; after changing it you must update the endpoint in DSH too — mismatched ports always fail to connect.
3. Has the model finished loading? Local models take tens of seconds to load the first time; requests sent before loading completes time out or error. Wait for the log to show the model is ready, then retry.

One more local-model gotcha: resource exhaustion. If the model loaded but every request errors or the process dies mid-conversation, check RAM/VRAM — a local model that exceeds available memory crashes or refuses requests. Also confirm you did not start two local services on the same port; the second one silently fails while the first keeps serving.

Full steps for connecting local models are in Use local AI models with DeepSeek Harness.

After connecting a local model, model-related DSH plugins such as token usage and cost tracking can be picked from the model category in DSH Plugin Hub — they help confirm each call really goes through, making it easier to compare cloud and local models.

Notes

1. The API key takes effect immediately after saving — no restart needed.
2. When switching models, update the endpoint and model name together; mismatches fail to connect.
3. headless mode uses the same model config; dsh --dump-config confirms it.
4. The error message points the way: 401/403 → key and quota, 404 → model name and endpoint, timeouts → network and proxy.

Source: official Quickstart, dsh CLI README