DeepSeek Harness Custom Model Service: 2026 Setup Guide

A custom provider is not a general-purpose model switch. It is an endpoint definition for a service that the installed provider catalog does not already describe.

For the official DeepSeek API, the built-in route is normally the safer choice. It avoids manually entering an endpoint, protocol, credential reference, and model list. The catalog route also gives DeepSeek Harness the provider-specific behavior it already knows.

A custom provider becomes appropriate when:

• The request must pass through a company model gateway.
• The model is served by a self-hosted inference service.
• The endpoint is not included in the installed provider catalog.
• The organization needs a separate credential, audit route, or network boundary.
• The gateway exposes an OpenAI-compatible API but uses its own model identifiers.

The key distinction is whether the endpoint is already represented by a catalog entry, not whether the model name happens to be similar.

The official guide states that catalog providers use their installed catalog without making a model-list network request, while a custom provider can query the endpoint shown in the form. That difference explains why two providers with the same underlying model may behave differently during setup. See the official model configuration details before copying any field from an older screenshot or community post.

Decision checklist

• [ ] The target is the official DeepSeek API.
• [ ] The target provider already appears in the installed catalog.
• [ ] The endpoint is a company gateway or self-hosted service.
• [ ] The endpoint has a documented API protocol.
• [ ] The team knows the exact model ID exposed by the endpoint.
• [ ] A credential can be stored without placing a secret in source control.
• [ ] A previously verified route can be used for rollback.

If the first two items are true, start with the built-in or catalog route. If the third or fourth item is true, continue with a custom provider. Do not create a custom provider merely to rename an existing catalog model.

The configuration has four separate jobs. Treating them as interchangeable is a common cause of confusing failures.

The Provider ID deserves special attention. According to the official guide, it is permanent because requests, saved sessions, model defaults, and credential references use it. The display name, Base URL, protocol, credential, and model list can be edited, but renaming the Provider ID requires adding a new provider and deleting the old one.

That makes the ID an operational identifier, not a cosmetic label. Names such as team-gateway, staging-router, or self-hosted-prod communicate purpose, but the final choice should reflect how the route will be managed months later. Avoid names tied to a temporary model version unless the route itself is temporary.

The Base URL is the network address, not automatically the full request URL. The endpoint may require a version or API prefix. The only safe approach is to compare the gateway documentation with the field description in the current DeepSeek Harness interface. Do not append paths based on assumptions from another client.

The API protocol determines how DeepSeek Harness formats requests. An endpoint may be marketed as “OpenAI compatible” while supporting only a subset of the expected request shape. Compatibility should therefore be treated as a test result, not a marketing claim. Check whether the service supports the request path, authentication header, model field, streaming behavior, and tool-call format required by the harness.

The credential solves authentication. It does not prove that the model exists, that the protocol is correct, or that the endpoint accepts tools. The provider guide states that keys are write-only in the Web UI and that the stored configuration keeps a credential reference rather than exposing the literal secret. Follow the credential storage behavior documented by DeepSeek Harness, and never commit a real key to a project repository.

Open the model settings and choose the custom provider option. The exact wording may change during the developer preview, so the current interface should be treated as authoritative over older tutorials.

Enter the required identity and connection details in this order:

1. Choose the lowercase Provider ID.
2. Enter the display name, if the interface provides one.
3. Enter the Base URL supplied by the gateway or self-hosted service.
4. Select the API protocol that the endpoint actually implements.
5. Select or create the credential reference.
6. Add at least one model ID.
7. Use model discovery when the endpoint supports it.
8. Save only after reviewing the complete draft.

The provider guide requires a lowercase Provider ID, Base URL, API protocol, credential, and at least one model for a custom provider. It also explains that model discovery queries the Base URL and credential currently shown in the form. Selecting a returned model updates the draft; the provider is not stored until the final save.

That distinction matters. A model appearing in a temporary discovery result does not mean the provider has been saved. Conversely, a provider appearing in the model picker does not prove that a request will succeed.

Why does a saved custom provider show no model?

There are three likely explanations:

• The provider saved without a valid model entry.
• The endpoint does not expose a model directory.
• The returned model ID differs from the ID required in the request.

The first check is the model field itself. Compare the exact string shown by the gateway with the ID entered in DeepSeek Harness. Case, punctuation, namespace prefixes, and version suffixes can matter. A display name such as “Coding Model” is not necessarily the request model ID.

The second check is model discovery. The official guide says that DeepSeek Harness uses the OpenAI-compatible GET /models endpoint when fetching available models. An endpoint that supports chat completions but does not implement /models may still be usable, but the model must be entered manually.

How should a 401 from model discovery be handled?

Treat a 401 as an authentication problem first. Check that the credential belongs to the selected provider, that the secret has not expired, and that the gateway accepts the authentication method expected by the configured protocol.

Do not solve a 401 by changing the model ID. Model selection happens after authentication. Also do not assume that a successful browser login proves that the API credential is valid; the model discovery request may use a different header, scope, or service account.

If the gateway intentionally does not expose /models, skip discovery and enter the known model ID manually. That is different from ignoring a 401. A missing model directory is a capability limitation. A 401 indicates that the request reached an authentication boundary and was rejected.

The official model API reference describes the standard model-list shape and the GET /models operation. A gateway does not have to reproduce every detail, but the reference provides a useful baseline when the service claims OpenAI-compatible API support.

A saved provider should be verified in an isolated workspace and a new session. The official Web UI guide explains that a workspace must be selected before the session composer becomes available, and that model changes apply to the next request without restarting the server. The Web UI workflow is therefore a useful reference for separating workspace problems from provider problems.

Use this five-stage acceptance sequence:

Stage 1: Confirm the selected route

Open a new session and verify that the model picker shows the intended Provider ID and model. Record the selected values in the test log. If the provider is not selectable, stop here and fix configuration rather than sending requests through an unknown default.

Stage 2: Send a minimal text request

Use a short prompt that does not require repository access, long context, or special output formatting. The success signal is a normal assistant response from the expected model route.

Record:

• Provider ID.
• Model ID.
• Request time.
• Response status.
• Visible error text.
• Whether streaming was enabled.
• Whether the response ended normally.

A successful response proves basic authentication and text request compatibility. It does not prove tool support.

Stage 3: Repeat with a fresh turn

Send one follow-up message in the same new session. This checks whether the endpoint accepts the conversation history that DeepSeek Harness sends after the first response. Some gateways handle single-turn prompts but reject message fields or role sequences in multi-turn requests.

Stage 4: Run one controlled tool call

Use a harmless tool with a deterministic result, such as reading a test file or returning a fixed local value. Do not begin with a production repository, destructive command, or broad filesystem permission.

A successful tool call requires more than text generation. The endpoint must accept the tool schema, return a valid tool-call structure, allow the harness to execute the tool, and accept the tool result in the next request. The official chat API reference can be used as a protocol baseline, but it does not prove that a particular gateway implements every feature.

Stage 5: Force the fallback test

Temporarily make the custom route unavailable in the test environment or select the previously verified route manually. Start another new session and run the same minimal text task. The fallback is acceptable only if the request reaches the intended route and produces a diagnosable result.

Do not declare success because the settings page saved. The acceptance target is a complete chain:

credential -> endpoint -> model discovery or manual model -> text request -> tool call -> fallback

Will an existing session switch automatically after the model changes?

No. The official provider guide states that selecting a model makes it the default for new sessions, while a session that has already sent a request retains the model recorded in its own log.

This behavior protects conversation consistency. A session that began on one provider should not silently continue on another provider with different context limits, tool behavior, or output semantics.

Use this switching procedure:

1. Save or update the provider.
2. Confirm the new model appears in the picker.
3. Start a new session.
4. Send the minimal text request.
5. Repeat the controlled tool call.
6. Keep the previous session available for comparison.
7. Only after validation, make the new route the team default.

If a saved default points to a deleted provider, the composer may require another model selection before input is allowed. Do not keep editing the old session to hide this state. Create a new session and select a valid route.

This matters during migrations. An old session can remain useful as a comparison record, but it should not be treated as evidence that the new provider works.

Custom model services introduce configuration drift in at least four places:

• Endpoint URL.
• Credential reference.
• Model ID.
• API protocol or gateway adapter.

Record every change with the date, operator, reason, old value, new value, validation result, and rollback route. Keep secrets out of the record. Store only the credential reference or an approved secret identifier.

Keep one verified route available until the replacement passes the same tests. A fallback that has not been exercised recently is only a configuration entry, not a recovery plan.

After upgrading DeepSeek Harness or the gateway, repeat the minimal text request and controlled tool call. The repository currently describes DeepSeek Harness as a developer preview with compatibility-breaking changes possible, so production teams should pin the tested version and review the current project README before upgrading.

A remote Mac environment can be useful when the model gateway must be tested alongside macOS tooling, signing workflows, local scripts, or an agent workspace that must remain online. It should not replace the provider validation sequence above.

The current gateway setup may have several weaknesses if it is tested only from a developer laptop:

• The laptop may disappear from the network or sleep during a long agent run.
• Local credentials and shell settings may differ from the team’s reproducible environment.
• A laptop test may not reveal restart persistence or permission problems.
• A shared gateway may be reachable from one network but blocked from another.

For a temporary validation project, a remote Mac test environment can isolate the harness, preserve the workspace, and provide a consistent place to repeat the same request after a gateway or harness update. NUKCLOUD’s remote Mac environment options can be reviewed after the endpoint passes the local protocol checks. If the team already knows the required region, the US East Mac environment is one possible starting point.

The decision should remain conditional:

• Choose a remote Mac when the requirement is temporary, isolated, continuously available validation.
• Choose a self-owned Mac when the workload is stable, persistent, and requires dedicated physical access.
• Choose a local workstation when the test is short and network conditions are not part of the acceptance criteria.
• Do not rent a Mac merely to compensate for an incorrectly configured Provider ID, Base URL, credential, or model ID.

A gateway tested only through a laptop remains vulnerable to environment-specific assumptions. A gateway tested through a repeatable remote Mac workflow is easier to compare before and after a configuration change, provided the team still records the actual provider, model, response status, and fallback result.

For model platform teams, the practical sequence is therefore simple: keep the official DeepSeek route on the built-in path, reserve custom providers for directory-outside services, fix the Provider ID before saving, validate discovery separately from inference, and use a new session for every model switch. If the gateway needs an isolated macOS host that stays online during repeated acceptance runs, NUKCLOUD can provide the temporary test environment; the provider should still earn approval through the text, tool, and rollback checks above.