Why DeepSeek Harness API Keys Are Write-Only After Saving
A DeepSeek Harness model key disappears after saving because the whole path is write-only: the page gets a masked descriptor, the plaintext lives in $DSH_HOME/.credentials.yaml, and settings keeps only a credential reference. Once you accept that, the dots and partial characters stop looking like a bug.
DeepSeek Harness: The write-only contract
Write-only means “write it in, never read it out,” not “hide it until you click an eye.” The official docs say the key is write-only: after saving, the page receives only a masked descriptor and never the plaintext (source).
Two consequences follow. First, the settings page cannot offer “show saved key,” because the browser has no plaintext to show. Second, any request that needs the key resolves the credential reference on the host side rather than sending the plaintext back from the page.
This is stronger than a front-end mask. A mask is visual; opening developer tools can still find the value. Write-only is a data-flow property: after saving, the response contains only a descriptor, so there is nothing to recover.
The partial characters are therefore an identity hint, not a way to verify the full secret. If the identifier and the visible edges match the key you meant to save, the right credential is active.
DeepSeek Harness: Where the key lands
The plaintext goes to $DSH_HOME/.credentials.yaml; settings keeps the reference. That split explains why the key is invisible in the UI (source).
It also explains three behaviors:
- Why the settings page never shows plaintext — it reads settings, not the credential file.
- Why a new home loses the key — the credential follows the home, not the browser.
- Why several providers can share one key — they can point to the same credential reference.
When you back up or migrate, copying cordis.patch.yml is not enough. The credential file and the home belong together. Migrate the config without the credential and the request will report a missing credential even though everything “looks configured.”
Check four things before migrating:
- Old home — which directory the old machine used as
DSH_HOME. - Credential file — back up
.credentials.yaml, not only the profile. - Reference name — the new settings must point to the same credential reference.
- One request — send a short task after migration, before relying on a real workload.
If the new environment uses an environment variable, you can skip the credential file, but the variable name must match the one the route declares. See The DeepSeek Harness API key lifecycle.
DeepSeek Harness: How the masked preview works
The preview follows explicit rules, not a generic asterisk replacement. It keeps the identifier before the first hyphen or underscore and the first five and last four characters of the key, but at least eight characters must remain hidden; otherwise the whole string and identifier become dots (source).
Two easy misreads follow:
- A short key may be all dots. If the visible edges would cover too much, the rule hides everything. That is protection, not a failed save.
- The identifier is not the key prefix. The preview first keeps the identifier before the first hyphen or underscore, then shows the key edges. A matching identifier confirms the category, not the secret.
| Case | Preview | Meaning |
|---|---|---|
| Long key | identifier + first five + dots + last four | At least eight characters hidden |
| Short key | all dots, including the identifier | No character can be shown safely |
| Identified key | identifier preserved | Identifier comes from before the first hyphen or underscore |
A saved key usually shows a “using saved key” note. That note is a state label, not a reveal button.
DeepSeek Harness: Replace, delete, and cancel
A saved key cannot be partially edited; every change is whole-item. The official behavior is specific (source):
- Replace — typing or pasting replaces the saved key as a draft; it takes effect after Save.
- Stage deletion — Backspace or Delete stages a whole-item deletion, and the UI says saving will use environment authentication.
- Cancel — cancelling before Save keeps the original key and discards the draft or staged deletion.
- Clear the draft — clearing a replacement draft also stages deletion of the saved key.
The common trap is “I deleted it but nothing changed.” Backspace only stages the deletion; Save applies it. Conversely, Cancel restores the original state if you only wanted to inspect the field.
Two edge cases matter. A rejected deletion leaves settings unchanged. If the key was deleted but the settings save failed, the UI warns that the deletion cannot be undone; retry Save to finish the configuration update, or close and keep the partial result. Retry rather than repeating the delete.
DeepSeek Harness: Clearing the key: environment fallback and shared references
Clearing the stored override is not the same as “no credential.” It can fall back to environment authentication (source).
Three outcomes:
- The environment has the variable — requests may keep working, now from the environment.
- The environment lacks it — the provider has no authentication and the next request fails.
- The reference is shared — clearing it affects every feature that uses the same reference, not just this model card.
Before deleting, ask whether the key belongs only to this provider. If not, clearing it can break search, another model, or a plugin. To rotate, add the new key first, verify a request, then remove the old credential.
DeepSeek Harness: Three checks and three misreads
Check the request, not the field. Three steps (source):
- State — the masked preview and the “using saved key” note show a stored override.
- Request — send a short task with the current model and confirm it returns.
- Fallback — if you intend to use the environment, confirm the variable exists before deleting the override.
Three common misreads:
- “Invisible means it was not saved.” Under write-only, invisible is normal; judge by the preview and the request.
- “I cannot copy it, so it is broken.” Saved keys are not copyable; only a replacement draft has the eye button.
- “Deleting it makes me safe.” Deletion removes the stored override; environment variables, shared references, and other homes may still hold copies.
With those checks, the model key page stops being a black box. Model list refresh and session-scoped model switching are covered in the next articles.
FAQ
The DeepSeek Harness key is write-only. After saving, the page receives a masked descriptor rather than the plaintext, so the preview only confirms which key is active.
DeepSeek Harness stores the key in $DSH_HOME/.credentials.yaml; settings keeps only a credential reference. That is why the settings page cannot display the plaintext.
A saved DeepSeek Harness key is write-only by design. It has no reveal, copy, cut, or partial-edit action; a replacement draft is the only place where the eye button applies.
DeepSeek Harness does not always behave that way. DeepSeek Harness falls back to environment authentication after you remove the stored override; requests fail only if no matching environment variable exists.
Related Terms
- write-only key
- A write-only key is a DeepSeek Harness credential that can be saved but never read back as plaintext; the page receives only a masked descriptor.— DeepSeek Harness docs - Configuring models
- masked preview
- A masked preview is the DeepSeek Harness display for a saved key; it keeps the identifier and a few leading and trailing characters while hiding at least eight.— DeepSeek Harness docs - Configuring models
- credential reference
- A credential reference is the settings value that points to a saved DeepSeek Harness credential; several features can share one reference.— DeepSeek Harness docs - Configuring models
- environment fallback
- Environment fallback is how DeepSeek Harness looks up a declared environment variable when no stored key override exists.— DeepSeek Harness reference - API key provider
Sources
- DeepSeek Harness docs - Configuring models· deepseek-harness
- DeepSeek Harness reference - API key provider· deepseek-ai