Preface

The credentials-local plugin for DeepSeek Harness (DSH) stores API keys in files on the agent host. File permissions can restrict ordinary users, but they cannot prevent the model process itself from accessing keys, and they make it difficult to rotate or audit keys consistently across multiple machines.

The dsh-credentials-vault plugin addresses these issues by integrating with HashiCorp Vault. It moves provider keys from the host to Vault, provides machine authentication through the AppRole mechanism, supports key rotation without restarts, and uses Vault audit devices to record all read operations.

What is it?

dsh-credentials-vault is a HashiCorp Vault backend for the DSH credential seam (ctx.credentials). It is maintained by user tancheng33 and licensed under MIT.

The plugin’s core purpose is to replace credentials-local, allowing DSH running in headless environments, containers, or CI agents to securely retrieve and rotate keys without keeping long-lived key files on the agent host.

Core Features

Based on verified facts, the plugin provides the following capabilities:

  • Centralized rotation: After a key is changed in Vault, DSH agents can use the updated value.
  • AppRole machine authentication: The agent host holds the AppRole Role ID and Secret ID, which are used to obtain temporary tokens rather than long-lived keys.
  • Key rotation without restarts: Through the CAS mechanism in KV v2 and real-time reads (default configuration), once a Vault value is changed, the next LLM request can use the new key without restarting the agent process.
  • Audit support: Vault audit devices record all key read operations.
  • Environment compatibility: Supports headless mode, container environments, and CI agents.
  • Concurrency control: Uses the KV v2 Compare-and-Swap (CAS) mechanism to prevent concurrent write conflicts.

Installation and Activation

Installing the plugin requires using DSH’s plugin management command.

dsh plugin --profile <name> add dsh-credentials-vault

After installation, you need to override the default behavior in DSH’s configuration file. DSH’s plugin mechanism defines implementations through a cordis.patch.yml file.

Typical Usage

In the configuration file (such as cordis.patch.yml), declare the id as credentials-vault and provide the Vault connection information.

- id: credentials-vault
  config:
    address: https://vault.internal:8200
    mount: secret
    path: dsh
    kvVersion: 2
    approleMount: approle
    roleIdRef: VAULT_ROLE_ID
    secretIdRef: VAULT_SECRET_ID
    environmentWins: true
    cacheTtlMs: 0
    timeoutMs: 10000

In Vault, keys are stored as a flat map under the specified path. DSH reads them using credential references (such as DEEPSEEK_API_KEY) as key names.

vault kv put secret/dsh DEEPSEEK_API_KEY=sk-... OPENAI_API_KEY=sk-...

Configuration Reference

Installation and configuration mainly involve the following parameters:

Configuration Item Description
address The Vault service address. Defaults to http://127.0.0.1:8200.
namespace Vault Enterprise namespace. An empty string means no namespace is used.
mount Mount point for the KV secrets engine. Defaults to secret.
path Subpath where keys are stored. Defaults to dsh.
kvVersion KV engine version. Defaults to 2, enabling CAS and version control.
tokenRef Environment variable name used to store the static token.
roleIdRef / secretIdRef Environment variable names used to store the AppRole Role ID and Secret ID.
readOnly Whether to reject write operations. Defaults to false.
environmentWins Whether environment variables override Vault values. Defaults to true.
cacheTtlMs Cache time-to-live. 0 means Vault is read on every request, with no caching.
timeoutMs Request timeout. Defaults to 10000.

Note: The configuration file should not contain any actual secrets. Confidential values (such as Token, Role ID, and Secret ID) must be injected via environment variables and read by the plugin.

Applicable Scenarios and Caveats

The plugin is suitable for scenarios that require strict auditing, centralized key management, or operation in CI/CD environments.

Before using it, be aware of the following limitations and characteristics:

  1. KV Secrets Engine only: The plugin currently supports only the HashiCorp Vault KV secrets engine. It does not support other dynamic secret engines such as database, PKI, or transit.
  2. Single path and flat mapping: All credential references must be stored in a flat key-value map under the same path.
  3. AppRole mechanism: In AppRole authentication mode, the plugin does not support automatic token renewal; it only supports periodic re-authentication. This has minimal impact in high-frequency call scenarios.
  4. Unaware of external changes: If Vault keys are modified through other means (not the plugin), DSH agents do not automatically detect the changes and update the cache unless the cache expires or the agent restarts.
  5. Runtime permissions: The plugin does not prevent a running agent process from making network requests with authorization keys it has already obtained. This is a key security boundary concern and belongs to the network layer (for example, dsh-egress-guard), not to the credential loading plugin.

Summary

dsh-credentials-vault provides the ability to migrate DeepSeek Harness credential management from local files to HashiCorp Vault. Through the AppRole mechanism and headless support, it meets the needs of modern DevOps and security auditing. For all configuration items and source code, refer to the GitHub repository.