Custom providers let PandaNpc use an API account, private gateway, or local model endpoint that you control. This is commonly called BYOK: bring your own key. It is useful when you need a model outside the built-in catalog, provider-side billing, an internal proxy, Ollama, LM Studio, or a self-hosted OpenAI-compatible service.
For supported direct chat, PandaNpc sends the request to your configured endpoint rather than substituting a built-in model. Your upstream provider still controls pricing, retention, rate limits, model availability, and acceptable use.
Prerequisites and security boundaries
Before adding a provider, collect:
- The provider's API key or local authentication token.
- Its API Base URL, normally ending in
/v1for an OpenAI-compatible service. - The exact model identifier accepted by the API.
- The documented context window and maximum output limit, if you plan to override defaults.
Use a dedicated key with the minimum necessary permissions and a spending limit where the provider supports one. Never place the key in documentation, chat prompts, screenshots, browser console output, or a Git repository.
In a web browser, direct requests are subject to CORS. The provider must allow requests from https://pandanpc.com. A Base URL such as http://localhost:11434/v1 refers to the computer running the browser, not automatically to the remote PandaPaw machine. The desktop app can be more suitable for local endpoints because it is not limited by browser CORS in the same way.
Step 1: Open Model Configuration
Sign in to PandaNpc and open Model Configuration. Providers and models are separate records: the provider stores connection and authentication details, while each model stores the identifier and limits sent to that connection.
If an official provider already appears, configure or copy it instead of inventing a different protocol. For a new OpenAI-compatible gateway, select Add Provider.
Step 2: Add the provider
Complete the provider form:
| Field | What to enter | Example or guidance |
|---|---|---|
| Display Name | A label visible to you | Company AI Gateway |
| Provider ID | A stable internal identifier | company-openai |
| API Key | The secret used as a bearer token | Provider-issued value |
| Base URL | API root without /chat/completions |
https://gateway.example.com/v1 |
| Protocol | The upstream API format | Choose openai for OpenAI-compatible chat completions |
| Secret | Optional second secret | Leave empty unless the provider requires it |
| Organization | Optional organization identifier | Only when required by the provider |
| Project | Optional project identifier | Only when required by the provider |
| Support content array | Whether message content may use structured arrays | Keep enabled for providers that accept modern multimodal message content |
PandaNpc removes trailing slashes from the Base URL and appends /chat/completions for the direct OpenAI-compatible chat request. Therefore enter:
https://api.example.com/v1not:
https://api.example.com/v1/chat/completionsSave the provider before adding a model. When editing an existing provider, an empty API Key or Secret field means “keep the configured value”; it does not expose the stored secret back to the form.
Step 3: Add a model
Choose Add Model under the provider and complete these fields:
| Field | Meaning | Example |
|---|---|---|
| Display Name | Human-readable selector label | My Coding Model |
| Model Value | Exact upstream model ID | model-name-from-provider |
| Model Type | PandaNpc capability/category mapping | Select a current value from the form |
| Provider | Provider record created above | Company AI Gateway |
| Context Window | Total supported tokens | Use the provider's documented integer limit |
| Max Tokens | Maximum generated output tokens | Use a positive value no larger than the provider limit |
Display Name can be changed without affecting the API call. Model Value cannot be guessed from a marketing name; copy it from the provider's API documentation or model-list endpoint.
Leave Context Window and Max Tokens empty when you are unsure. A conservative default is safer than declaring a context window larger than the server supports. These fields are especially important for PandaCode because they influence compaction and output budgeting.
Common endpoint examples
The following patterns illustrate URL shape; availability and model IDs depend on your installation or provider account:
| Service type | Typical Base URL | Notes |
|---|---|---|
| OpenAI-compatible cloud API | https://provider.example.com/v1 |
Must support streamed Chat Completions and bearer authentication |
| Ollama on the viewing computer | http://localhost:11434/v1 |
Start Ollama's OpenAI-compatible endpoint; browser use may require CORS configuration |
| LM Studio on the viewing computer | http://localhost:1234/v1 |
Start the local server and select a loaded model ID |
| Private network gateway | https://ai.internal.example/v1 |
The PandaNpc client must be able to resolve and reach the host |
Do not assume that every service advertising “OpenAI compatible” implements streaming, tool calls, images, reasoning fields, or identical error responses. Test the exact features your workflow needs.
Verify the provider and model
Use a low-cost, non-sensitive prompt before relying on the configuration:
- Select the new model in a fresh conversation.
- Send
Reply with exactly: provider connected. - Confirm that the response streams and the provider dashboard records the request.
- Send a short follow-up to verify conversation history.
- If you need tools, images, or long context, test each capability separately.
For a local endpoint, first verify it outside PandaNpc. An OpenAI-compatible model list is often available with:
curl http://localhost:11434/v1/modelsUse the response only to confirm reachability and the model ID. Do not put a production API key directly into shell history.
Use custom models with PandaCode
PandaCode can provide a Claude Code-style coding workflow while using a model backend you choose, including DeepSeek, Qwen, an OpenAI-compatible gateway, or an internal service. After configuring the provider and model, select that model for the relevant PandaCode connection or task.
The model must support the interaction pattern required by the coding engine. A provider that works for plain chat may still fail on tool calls, long-running streams, or structured content. See AI models supported by PandaNpc for the difference between chat models and local coding engines, and PandaPaw installation and commands for remote engine setup.
Troubleshooting
`401` or `403` authentication error
Create a new provider key, confirm it is active, and re-enter it. Check whether the upstream service requires an organization, project, or different authentication method. A masked key copied from an edit screen is not the original secret.
`404` endpoint or model not found
Remove /chat/completions from the configured Base URL because PandaNpc appends it. Confirm that /v1 is present when required and that Model Value exactly matches the upstream model ID. A provider may return the same 404 for both a wrong URL and an unavailable model.
Browser reports a network or CORS error
Open the browser developer console only to identify the blocked origin; do not paste secrets there. Configure the provider to allow https://pandanpc.com, use its HTTPS endpoint, or use the PandaNpc desktop app. Mixed content rules block an HTTPS page from calling some plain HTTP endpoints.
Local Ollama or LM Studio cannot be reached
Make sure the server is running on the same computer as the client making the request and is listening on the configured interface and port. If the model server runs on another computer, localhost is wrong; use a reachable private hostname or IP and secure the service before exposing it.
Response starts but stops or has no content
Confirm that the API supports streamed Chat Completions and emits standard data: events. Reduce Max Tokens, test a text-only message, and disable structured content arrays only if the provider documents that it accepts string content exclusively.
Long sessions fail near the context limit
Lower the configured Context Window to the provider's real supported limit and reserve room for output, system instructions, and tool results. Start a fresh session after changing the model configuration so the new limits are applied consistently.
For account-level quota and data-flow details, read PandaNpc accounts, plans, and API costs and the Privacy Policy.