Providers & Keys

Harness is model-agnostic. Model access is a plugin (the llm-pi-ai provider), and routes are configured in $DSH_HOME/settings.yaml under llm-pi-ai.providers.<route>. Keys never live in settings: they're stored write-only in $DSH_HOME/.credentials.yaml, and settings.yaml references them by name.

The Models page

In the web UI, Settings → Models is the primary surface:

• DeepSeek — one API-key field; enter the key and save.
• Add provider — pick a catalog provider (Anthropic, OpenAI, and others); the installed catalog supplies the endpoint, protocol, and model list. Native-auth providers (Bedrock, Vertex, Azure, Codex) need their native credentials, not just a key.
• Add a custom provider — for a gateway, self-hosted server, or a provider absent from the catalog. Fill in Provider ID (lowercase, permanent), display name, base URL, API protocol, credential, and at least one model. Fetch available models queries the endpoint and fills the list.

Keys are write-only: the page shows a redacted descriptor after saving, never the literal secret.

settings.yaml

A provider route in $DSH_HOME/settings.yaml:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: my-model
agent-default-model:
  provider: my-gateway
  model: my-model

Provider fields: apiKeyEnv (credential ref), api (protocol: openai-completions, openai-responses, anthropic, ...), baseURL, models, input / defaultInput (image modality), compat (request-shape switches), modelOverrides. Selecting a model in the picker also sets it as the default for new sessions.

OpenCode Zen/Go keys

OpenCode publishes two gateway products, and dsh ships a catalog route for the subscription one:

• OpenCode Go — https://opencode.ai/zen/go/v1, a $10/mo subscription ($5 first month). The subscription is per-workspace, and only one member per workspace can subscribe. Usage is dollar-limited ($12/5h, $30/wk, $60/mo).
• OpenCode Zen — https://opencode.ai/zen/v1, pay-per-use, with optional auto-reload and monthly limits; bring-your-own-key is supported for OpenAI/Anthropic.

DeepSeek V4 Pro and V4 Flash are served on both endpoints via OpenAI-compatible chat/completions.

The base bundle mounts an opencode-go catalog route — endpoint, protocol, and DeepSeek models with thinkingFormat: deepseek preloaded. Its credential ref is OPENCODE_API_KEY. Add the key once:

$DSH_HOME/.credentials.yaml:

version: 1
refs:
  OPENCODE_API_KEY: sk-your-opencode-key

Then either select the route on the Models page, or hand-declare it in settings.yaml (this is the form configured on this machine):

llm-pi-ai:
  providers:
    opencode-go:
      apiKeyEnv: OPENCODE_API_KEY
      api: openai-completions
      baseURL: https://opencode.ai/zen/go/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash
agent-default-model:
  provider: opencode-go
  model: deepseek-v4-flash

Notes:

• apiKeyEnv must be OPENCODE_API_KEY — the catalog's credential ref for opencode-go. A different name won't resolve.
• The catalog route already ships api/baseURL/models and the thinkingFormat: deepseek metadata; the hand-written block is only needed to override.
• The Go subscription is per-workspace — mint the key in a workspace subscribed to Go, otherwise requests fail with Insufficient balance.
• For pay-per-use Zen, use a custom provider with baseURL: https://opencode.ai/zen/v1 (the same key authenticates both).
• Credential resolution: env → $DSH_HOME/.credentials.yaml → cwd .env → $DSH_HOME/.env.

Custom OpenAI-compatible gateways

pi-ai decides the request shape from the endpoint URL and treats unknown addresses as OpenAI. Two switches fix most gateways:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: my-reasoner
          compat:
            thinkingFormat: deepseek

• supportsDeveloperRole: false — a reasoning model sends its system prompt as role: "developer", which many gateways reject.
• maxTokensField: max_tokens — servers that only know max_tokens refuse max_completion_tokens.
• thinkingFormat: deepseek — per model, for DeepSeek-style reasoning_content.

Image-capable models need input on the model or defaultInput on the route:

models:
  - id: vision-preview
    input: [text, image]

Troubleshooting

• MISSING_CREDENTIAL — store the key (Models page) or supply the referenced env var.
• UNKNOWN_MODEL — select a configured model, or add it to the custom provider.
• Fetching available models returns 401 — bad key. Model discovery calls GET /models.
• Gateway refuses every request with a right key/URL — start with compat.supportsDeveloperRole: false + compat.maxTokensField: max_tokens.
• Insufficient balance on opencode-go — the Go subscription is per-workspace; the key must come from a subscribed workspace.