DeepSeek Harness Integration with B.AI API Official Configuration Guide

DeepSeek Harness is a highly anticipated open-source AI workspace application, currently in the developer preview phase. It not only delves deep into local workspaces to assist with code and file analysis, but also empowers developers with exceptional flexibility through its open custom Provider mechanism. B.AI, as an advanced AI infrastructure, has built a full-stack large model service platform integrating high availability and low latency, dedicated to constructing a powerful, stable, and highly elastic intelligent computing network for developers and enterprises.

This guide will provide a detailed demonstration of how to launch DeepSeek Harness from scratch on Windows, macOS, and Linux environments, and successfully integrate it with the B.AI API. By following this tutorial, you will establish a complete call loop from your local workspace to the large model, fully unleashing the potential of AI-driven production and innovation.

The resulting call chain: DeepSeek Harness → B.AI API → Model provided by B.AI

1. Preparing the Environment

DeepSeek Harness is launched using npx, which comes bundled with Node.js. Please ensure your system has a currently available Node.js LTS version installed.

Official download link: https://nodejs.org/en/download

• Windows

You can directly download the .msi installer, or search for PowerShell in the Start Menu, open it, and run the WinGet installation command.

winget --version
winget install --id OpenJS.NodeJS.LTS -e --source winget

• macOS

On the official Node.js download page, select the macOS Installer, download the .pkg file, and follow the prompts to complete the installation. After installation, press Command + Space to open Spotlight Search, type Terminal, and enter the terminal.

• Linux 

On the official Node.js download page, please select your Linux distribution and system architecture, and install the LTS version using the package manager commands provided on the page. As installation commands vary across different distributions such as Ubuntu, Debian, and Fedora, it is recommended to use the dynamically generated commands on the official page to ensure a smooth and error-free installation process.

After installation is complete, close all currently open terminal windows and open a new one (Windows users should use PowerShell, macOS users should use Terminal, and Linux users should use the system terminal).

On all three systems, run the same set of check commands below:

node -v
npm -v
npx -v

Once all three commands return version numbers, your environment is ready.

Node.js v24.19.0
npm 11.17.0
npx 11.17.0

If you plan to build and run the project from the GitHub source code, you will need a Git environment. First, run git --version in the terminal to check if it is installed. If not, execute the following commands according to your operating system:

Windows 

winget install --id Git.Git -e --source winget

macOS 

xcode-select --install

Ubuntu or Debian 

sudo apt update
sudo apt install git

Note: If you only plan to use the npx method for a quick trial and B.AI configuration, you can skip Git entirely.

2.  Launching DeepSeek Harness with npx (Recommended)

For developers using the tool and configuring the B.AI API, launching directly with npx is recommended.

Run the following command in the terminal (uniform across all three systems):

npx @deepseek-ai/dsh web

First-run prompt: The system will ask if you want to download the necessary packages. Type y and press Enter to confirm.

Need to install the following packages
@deepseek-ai/dsh@...
Ok to proceed? (y)

If you see dependency deprecation warnings during startup, this is a normal occurrence and requires no intervention.

npm warn deprecated node-domexception@1.0.0

When the terminal outputs a local address, it means the DeepSeek Harness web service has started successfully.

dsh web: http://127.0.0.1:3080

Keep the terminal window open, then enter the following address in your browser:

http://127.0.0.1:3080

This address is only accessible from your local machine. If you close the terminal window or press Ctrl+C in it, the local service will stop. If your browser cannot open 127.0.0.1:3080, first check if the terminal is still running and confirm that the above dsh web address is displayed within it. If necessary, re-run the startup command.

npx @deepseek-ai/dsh web

3. Building from Source Code (Advanced)

If you plan to develop plugins, modify the source code, or contribute to the project, you can also obtain the source code from the official GitHub repository.

Official repository: https://github.com/deepseek-ai/deepseek-harness

Please note that GitHub provides the project source code, which must be downloaded and then built via the terminal by installing dependencies. You cannot run it by simply double-clicking the files. You can obtain and run the source code in two ways:

Method 1: Download the ZIP source package. Click the green Code button on the repository page and select Download ZIP. After downloading and extracting, open a terminal, use the cd command to enter the extracted project directory, and run the following commands in sequence:

npm install -g pnpm
pnpm install
pnpm run build
pnpm dsh web

Method 2: Clone using Git. It is recommended to first run git --version to check if a Git environment exists. If not installed, refer to the "Preparing the Environment" section above to install Git for your specific system. After confirming the environment is correct, reopen the terminal and run the following commands:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
npm install -g pnpm
pnpm install
pnpm run build
pnpm dsh web

Regardless of whether you use the ZIP or Git method, once built and launched successfully, the access address is also http://127.0.0.1:3080.

4. B.AI Custom Provider Configuration

Step 1: Skip the Official Default Configuration

When you first enter DeepSeek Harness, a window for entering the official model's API Key will pop up. Be sure to click "Configure Later". If you enter a B.AI Key here, the system will not be able to recognize it correctly.

Step 2: Navigate to the Custom Configuration Page

Click on "Settings" in the bottom left corner of the page, select "Models" from the left menu, and click "Add Custom Provider" on the right. Note: The red dot displayed on the official Provider at this point is normal and does not affect subsequent operations.

Step 3: Fill in the B.AI API Information

Once the custom provider panel is open, fill it in with the following content.

Provider ID: bai
Display Name: B.AI
API Base URL: https://api.b.ai/v1
API Protocol: openai-completions
API Key: A valid API Key created from the B.AI console

Step 4: Fetch the Model Catalog and Complete Provider Creation

After filling in the basic information, scroll down to the "Model Catalog" section. The system offers two ways to add models: click "Add Model" to manually enter the model ID, or click "Fetch Available Models" in the top right corner.

Recommended Action: First, click "Fetch Available Models". This makes DeepSeek Harness directly request the catalog of models available for your current account from B.AI. If the model list returns successfully, it proves that the B.AI API Key, https://api.b.ai/v1, the openai-completions protocol, and the model catalog endpoint are all successfully connected.

Notes on Model Selection and Addition:

• From the returned list, check the DeepSeek models currently available on B.AI (examples may include deepseek-v4-flash or deepseek-v4-pro; please note that specific available models change dynamically based on account permissions and time, so always refer to the actual returned results).
• Do not modify the Model ID: The model ID must exactly match what B.AI actually returns. Do not arbitrarily change any capitalization, hyphens, or version numbers, as this can easily trigger a model not found error during subsequent calls.

After confirming the models are added correctly, scroll to the bottom of the form and click "Create Provider".

After successful creation, a new custom Provider named B.AI will appear on the settings page with a green dot next to it. This indicates that the B.AI custom Provider has been saved successfully and is available. Note: If the DeepSeek official Provider still shows a red dot at this point, it is because no DeepSeek official API Key has been entered. This does not affect the normal use of the B.AI endpoint corresponding to the green dot.

Step 5: Connectivity Verification

Close the settings window, return to the main interface, and start a new conversation. In the model selector, choose the B.AI Provider, then select the DeepSeek model you just added, and perform the following tests:

Basic Conversation Test: With B.AI and the corresponding model selected in the model selector, send this instruction:

Please introduce yourself and state the model you are currently using.

Observe if it returns content normally and whether there is streaming output. Also, confirm that the current Provider is B.AI and the model ID matches what you selected.

Tool Calling Test: Send a read-only instruction to verify the tool call chain:

Please look at the files in the current workspace and summarize the directory structure. Do not modify or delete any files.

The specific emphasis on "Do not modify or delete any files" in the instruction is to safely and quickly verify that Harness's tool calling chain is functioning correctly without altering the current workspace.

While performing the two tests above, please check the terminal window running DeepSeek Harness to ensure the console shows no 401, 404, model not found, or other request errors. If the terminal runs smoothly, you have successfully completed all integration and verification steps.

💡 Frequently Asked Questions Q&A

Q1: The terminal reports that the node, npm, or npx command is not found? 

A: This usually means Node.js hasn't been installed completely, or the newly installed command paths haven't been picked up by the current terminal. Close all terminal windows, reopen one, and run the commands again.

node -v
npm -v
npx -v

If the commands are still not found, return to the official Node.js download page and confirm you have installed the current LTS version. Windows users can also check for Node.js in the system's "Installed Apps"; macOS and Linux users can run which node to view the command path.

Q2: I see an npm warn deprecated message during startup, do I need to deal with it?

First, check if the following address appears afterward:

dsh web: http://127.0.0.1:3080

If this address appears correctly, it means the web service has started successfully. In this test, deprecated is a dependency deprecation warning and can be ignored. If the terminal subsequently exits unexpectedly or does not output the local address, troubleshoot based on the specific error message at the end of the terminal output.

Q3: The browser can't open 127.0.0.1:3080, what should I do?

A: First, check if the terminal window running dsh web is still open. Closing the terminal or pressing Ctrl+C will stop the local service.

If the service has stopped, re-execute the startup command:

npx @deepseek-ai/dsh web

If the terminal shows a "port is already in use" message: First, end any residual DeepSeek Harness processes, then try again.

Q4: I encounter a 401 Unauthorized error when calling the model, how can I troubleshoot it? 

A: A 401 error typically points to an API Key authentication failure. Please check the following:

• Ensure the API Key was copied completely with no extra spaces at the beginning or end.
• Verify that the API Key is active (not deactivated) in the B.AI console.
• Confirm that the Key was entered into the correct configuration section: it should not be placed in the "DeepSeek Official Provider" from the initial pop-up, but must be entered in the B.AI endpoint under "Settings → Models → Add Custom Provider".

Q5: When calling the model, I get a 404 Not Found error. What's filled in incorrectly?

   A: Please check if the API Base URL is complete.

https://api.b.ai/v1

Q6: I get a model not found prompt, how do I resolve it?

A: Return to the B.AI custom Provider's edit page and click "Fetch Available Models" again. Ensure that the model ID you selected or entered exactly matches the system's returned results, strictly preserving all capitalization, hyphens, and version numbers. Additionally, updates to your account permissions or adjustments to the official model catalog can render old models unavailable. If you encounter an error, always use the most recently fetched model list as the reference.

Q7: B.AI shows a green dot but I still can't have a conversation? 

A: A green dot only indicates that the configuration information has been saved. If you can't converse, first verify that the current session has correctly selected the B.AI Provider and the specific model, that the model ID is accurate