Use a self-hosted model provider

Last published : Nov 09, 2026
This guide shows you how to make a model you host yourself available in Knowledge Worker Agent, through central configuration. The example is a self-hosted Mistral endpoint. The same steps work for any endpoint that offers the OpenAI chat completions API.
Related information
Administer Knowledge Worker Agent

Before you start

You need:
  • An endpoint that offers the OpenAI chat completions API, and the models it serves. Every model must be able to call tools. Knowledge Worker Agent can't work with a model that can't.
  • Central configuration, with KWA_CENTRAL_CONFIG=true. Without it, Knowledge Worker Agent offers only its built-in providers, GitHub Copilot and Google Vertex AI, and your provider doesn't appear. To build the configuration into your workspace image, see Add Knowledge Worker Agent to your own workspace image. For a configuration repository, see Set up central configuration.

Describe the provider

Create artifacts/provider/mistral.json in the configuration:
{
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    "mistral-onprem": {
      // The endpoint speaks the OpenAI chat completions API.
      "npm": "@ai-sdk/openai-compatible",
      "name": "Mistral",
      "options": {
        // The base URL only. /chat/completions is added for you.
        "baseURL": "https://mistral.example.com/v1",
        // Read from the user's environment. No key in the image.
        "apiKey": "{env:MISTRAL_API_KEY}"
      },
      // A private endpoint has no public model details, so declare every
      // model, with its cost and limits.
      "models": {
        "mistral-large-latest": {
          "name": "Mistral Large",
          "cost": { "input": 2, "output": 6 },
          "limit": { "context": 128000, "output": 8192 },
          "tool_call": true
        },
        "mistral-small-latest": {
          "name": "Mistral Small",
          "cost": { "input": 0.2, "output": 0.6 },
          "limit": { "context": 128000, "output": 8192 },
          "tool_call": true
        }
      }
    }
  },

  "sds": {
    "auth": {
      "type": "managed",
      // The environment variable that holds the key. A name without "/"
      // is read as a variable, not a file path.
      "secretRef": "MISTRAL_API_KEY",
      "label": "Mistral",
      "help": "Provisioned from your SDS profile."
    },
    // The models behind the Default and Thinking presets, and the small
    // model that names chats.
    "presets": {
      "default": "mistral-onprem/mistral-large-latest",
      "thinking": "mistral-onprem/mistral-large-latest",
      "small": "mistral-onprem/mistral-small-latest"
    }
  },

  "model": "mistral-onprem/mistral-large-latest"
}
Change these for your endpoint:
  • The models. Replace the two examples with the model IDs your endpoint serves, and set their cost and limit. Without cost, every response reports no cost. Without limit, Knowledge Worker Agent can't show how much of the context is left.
  • The presets. Without presets, Default and Thinking look for a Claude model by name, find none, and users have no model to send with. The small model names chats, and isn't offered in the model list.
  • Authentication. The apiKey is sent as a bearer token in the Authorization header. If your endpoint expects something else, such as an Azure API Management subscription key, another header, or mutual TLS, set options.headers instead.

Assign the provider

In assignment.jsonc, register the file under an ID, and assign the ID to the project:
{
  "schema_version": 2,
  "artifacts": {
    "provider": {
      "provider.mistral-onprem.v1": { "path": "artifacts/provider/mistral.json" }
    }
  },
  "assignments": {
    "projects": {
      // Must match KWA_PROJECT_ID.
      "default": {
        "provider": ["provider.mistral-onprem.v1"]
      }
    }
  }
}
Assignments use the ID, never the path. An ID that isn't registered stops the whole configuration from being applied, with assignment references unregistered artifacts, so the workspace gets no configuration rather than quietly losing one provider.

Give users their API key

Don't build the key into the image. Each user adds their own in their SecurSpaces profile:
  1. Go to Profile > Security > Personal Secrets > Secrets as Environment Variables, and select Add Secret.
  2. Enter MISTRAL_API_KEY as the name, and the key for your endpoint as the value.
  3. Choose to inject it into all workspaces, or into specific ones.
SecurSpaces sets the variable when a workspace starts, so restart a running workspace after adding or changing the key. The keys come from whoever runs your endpoint, not from Mistral.

Check that it works

Start a workspace that has the configuration, and check that:
  1. Mistral appears under Accounts, and shows as connected.
  2. Your models appear in the model list.
  3. A message gets an answer.
If the provider is missing, KWA_CENTRAL_CONFIG probably isn't true, or the workspace's project doesn't have the provider assigned. Check the Configuration tab in Settings > Diagnostics. If the provider is there but not connected, MISTRAL_API_KEY isn't reaching the workspace. Check that the secret is injected into that workspace, and that the workspace was restarted after you added it.