Configure models and API keys safely

The recommended path is Settings → Models in the Web UI. A saved change applies to the next request without restarting the server.

Default storage

The DeepSeek API key is write-only: after the browser saves it, the UI receives only a redacted descriptor and cannot retrieve the plaintext value.

The default credential file is:

$DSH_HOME/.credentials.yaml

When DSH_HOME is not set, it is normally located at:

~/.dsh/.credentials.yaml

settings.yaml should contain only credential references, never literal secrets.

Environment variables

Use placeholders in the launch environment or a repository-root .env file:

DEEPSEEK_API_KEY=your_key_here
DEEPSEEK_BASE_URL=https://your-gateway.example

DEEPSEEK_BASE_URL is optional; omitting it uses the public API. Never commit real values or paste them into issues, screenshots, or terminal recordings.

Credential resolution order

From highest to lowest priority:

1. Environment variables inherited by the launch process.
2. $DSH_HOME/.credentials.yaml.
3. .env in the invocation directory.
4. $DSH_HOME/.env.

If the same key exists in several places, establish which layer is actually winning before changing credentials.

POSIX file permissions

Credential files with group or other permissions are rejected. Fix the mode with:

chmod 600 ~/.dsh/.credentials.yaml

Mode 0600 blocks other operating-system users, but processes running under the same user ID may still read the file. It is a prudent control, not a complete secret-isolation boundary.

Custom providers

A custom provider needs a stable lowercase provider ID, base URL, API protocol, credentials, and at least one model. Fetch available models sends an OpenAI-compatible GET /models request; enter models manually if the endpoint does not support it.

Provider IDs appear in requests, sessions, and credential references, so they cannot be renamed without impact. To rename one, create the new provider first and remove the old entry afterwards.