Model Configuration

In DeepSeek Harness, Large Language Models serve as the cognitive "brain" for planning and reasoning, connected into the execution engine through a standardized Provider Adapter Layer. Harness supports DeepSeek's native APIs out of the box, as well as catalog cloud providers, private enterprise proxies, local Ollama instances, and multimodal vision models.

This guide provides a comprehensive walkthrough for configuring model providers, credential management, local endpoints, and vision input declarations.

Configuring DeepSeek Native Models#

DeepSeek is the natively optimized provider in Harness, offering ultra-high prefix cache hit rates (99.93%) and cost-effective execution.

Setup Steps

1. In the Web UI, open Settings → Models from the bottom-left menu;
2. Locate the DeepSeek provider card;
3. Enter your API Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx;
4. Click Save to apply changes.

Hot-Reload & Secure Credential Storage

• Instant Hot-Reload: Changes take effect immediately on the next agent request without restarting the server;
• Isolated Storage: API keys are securely persisted in $DSH_HOME/.credentials.yaml. The UI only displays sanitized references to prevent accidental exposure.

Adding Catalog Cloud Providers#

Beyond DeepSeek, Harness includes pre-built catalog adapters for major LLM providers (Anthropic, OpenAI, Groq, etc.):

Standard Cloud Providers

1. In the Models settings view, click Add provider;
2. Select your provider from the catalog dropdown (e.g., OpenAI or Anthropic);
3. Enter the API Key and save.

Native Cloud IAM Credentials (AWS Bedrock / Azure / Google Vertex)

For enterprise providers using cloud IAM authentication:

• A standard API key alone will not authenticate;
• Fill in the required native fields such as AWS Region, Azure Resource Name, or Google Cloud Project ID.

Adding Custom & Local Providers (Ollama / vLLM / Gateways)#

For internal API gateways, reverse proxies, or self-hosted models running locally via Ollama / vLLM / LocalAI, register a custom provider.

Required Custom Provider Fields

Click Add a custom provider and configure the following parameters:

Example: Connecting to Local Ollama

With Ollama running locally on default port 11434, configure:

• Provider ID: ollama
• Base URL: http://localhost:11434/v1
• Protocol: openai-compatible
• Models: qwen2.5-coder:32b, deepseek-r1:14b

Multimodal Vision Models & Image Input#

By default, manually registered models are treated as text-only. If your model supports vision perception (e.g., gpt-4o, claude-3-5-sonnet, qwen-vl-max), explicitly declare image input support.

Add the input field in $DSH_HOME/settings.yaml:

# $DSH_HOME/settings.yaml
llm-pi-ai:
  providers:
    my-custom-gateway:
      baseUrl: 'https://api.example.com/v1'
      models:
        - id: 'qwen-vl-max'
          input: [text, image]    # Explicitly enable text and image modalities
        - id: 'deepseek-chat'
          input: [text]           # Text-only model

Once declared, screenshots, UI mockups, and architectural diagrams uploaded in conversations will be automatically encoded into the multimodal prompt stream.

Declarative Configuration (Docker & Headless Workflows)#

For headless deployments or CI/CD automated evaluation runners, manage configurations declaratively via cordis.yml or $DSH_HOME/settings.yaml:

# cordis.yml configuration example
plugins:
  # LLM Adapter Plugin
  '@deepseek-ai/dsh-plugin-llm-adapter':
    defaultProvider: 'deepseek'
    providers:
      deepseek:
        apiKey: 'env(DEEPSEEK_API_KEY)'
        defaultModel: 'deepseek-chat'
        models:
          - id: 'deepseek-chat'
            displayName: 'DeepSeek-V3 (General Coding)'
          - id: 'deepseek-reasoner'
            displayName: 'DeepSeek-R1 (Deep Reasoning)'
      
      ollama-local:
        baseUrl: 'http://localhost:11434/v1'
        models:
          - id: 'deepseek-r1:14b'

    # Global timeout & retry controls
    timeout: 60000
    maxRetries: 3

FAQ & Troubleshooting#

Q1: Do I need to restart the Web UI after changing model settings?

Answer: Absolutely not. DeepSeek Harness is built on a responsive microkernel architecture where all provider configuration updates are captured and broadcast dynamically across event streams. Once you update an API key, switch the default model, or add a custom provider in the Settings panel and click save, your very next prompt or conversation will immediately establish connections using the newest credentials. If a thinking task is already running in the background, Harness will gracefully finish the active turn and transition to the new settings without requiring any terminal restarts.

Q2: How do I connect to a local Ollama or private model?

Answer: Integrating local private models is straightforward. In the Settings view, click "Add a custom provider". First, give it a recognizable identifier (such as ollama-local), then enter the local Ollama service address in the Base URL field—typically http://localhost:11434/v1 (make sure to include the /v1 suffix to adhere to standard protocol paths). Next, select the OpenAI-compatible protocol, leave the credential field blank or enter any placeholder text, and finally add your locally pulled model names (such as deepseek-r1:14b or qwen2.5-coder:32b) and save. All inference computations will then execute entirely offline on your local GPU or CPU, eliminating cloud Token costs while ensuring private code and proprietary documents never leave your machine.

Q3: What should I do if I encounter 429 rate limit or timeout errors?

Answer: A 429 (Too Many Requests) error typically indicates that your API key has reached upstream requests-per-minute (RPM) or tokens-per-minute (TPM) concurrency limits, which can occur during intensive multi-turn code refactorings or long-running reasoning chains. Harness provides built-in self-healing solutions: first, you can enable exponential backoff retries in your local configuration, which pauses for a few seconds before retrying automatically without manual intervention; second, you can configure a fallback secondary provider in Settings, using DeepSeek official API as your primary channel while keeping a local model or backup service as failover. When primary quota is exhausted, Harness switches over seamlessly so your workflows are not interrupted.

Q4: Are my entered API keys secure? Will they be uploaded?

Answer: Completely secure with zero risk of exposure. DeepSeek Harness strictly enforces a "local-first, credentials-decoupled" architecture. All API keys entered in the Web UI are encrypted and persisted solely within your personal machine's user directory credentials file ($DSH_HOME/.credentials.yaml). The browser dashboard only displays sanitized masks. Even if you package your workspace project or push code to public GitHub repositories, version control only tracks placeholder environment variables. Your actual private keys remain locked on your local drive and are never transmitted to any third-party cloud servers.