Set up central configuration

Last published : Nov 09, 2026
This guide shows you how to give every workspace in a project the same connectors, model providers, agents, context, skills, and dictation vocabulary from one configuration repository.
For the file formats, see Configuration repository. For how the pieces fit together, see Central configuration.
Related information
Administer Knowledge Worker Agent

Before you start

You need:
  • A configuration repository with an assignment.jsonc file at its root. It can be a Git repository, or a folder inside the workspace image.
  • For a private Git repository, read access from the workspace. Knowledge Worker Agent runs plain git clone and git pull, so the credentials must come from the URL or from the workspace's Git setup, such as a credential helper, an SSH agent, or a .netrc file. There's no separate token setting.
  • The project ID of the workspaces you want to configure.
  • A way to set environment variables for Knowledge Worker Agent in those workspaces, for example in the workspace image.

Point a workspace at the repository

Set these environment variables for Knowledge Worker Agent:
Variable Value
KWA_PROJECT_ID The workspace's project ID, as used in assignment.jsonc.
KWA_CONFIG_REPO_URL A Git URL, or the path of a folder that holds the repository.
KWA_CENTRAL_CONFIG true, to put the workspace under central management.
With the first two set, Knowledge Worker Agent applies the project's agents, context, skills, connectors, and vocabulary at every start.
Important: Set all three variables together. If KWA_CENTRAL_CONFIG is on but KWA_PROJECT_ID or KWA_CONFIG_REPO_URL isn't set, nothing is applied. The workspace then has no agents, context, or skills at all, which looks like a broken install. A warning is logged at startup.
KWA_CENTRAL_CONFIG=true changes two more things:
  • The model providers you assign replace the built-in ones. Without it, assigned providers aren't shown.
  • The built-in connector catalogue isn't installed, and catalogue entries it installed earlier are removed if no one changed them.
A folder path is read in place, with no network access at startup. A Git URL is cloned into a cache folder at the first start and updated at each start after that. If the repository can't be reached, the last cached copy is used. Users see which configuration their workspace uses, and when it was applied, in Settings > Diagnostics. A workspace that has never reached it has no cached copy, and its configuration isn't applied. The cache is .system/config-repo in the Knowledge Worker Agent folder, or ~/.config/sds-config-repo in a workspace that hasn't moved its files into one folder yet. The earlier setting for it, SDS_CONFIG_CACHE_DIR, is a legacy setting.

Assign something to a project

Everything is assigned the same way, in assignment.jsonc:
  1. Add the file or folder to the repository, for example artifacts/mcp/docs.json.
  2. Register it under artifacts, with an ID and its path.
  3. Add the ID to the project's list under assignments.
{
  "schema_version": 2,
  "artifacts": {
    "mcp": {
      "mcp.docs.v1": { "path": "artifacts/mcp/docs.json" }
    }
  },
  "assignments": {
    "projects": {
      "proj_sales": {
        "mcp": ["mcp.docs.v1"]
      }
    }
  }
}
Changes apply the next time Knowledge Worker Agent starts in each workspace.
To change an artifact, add it under a new ID, and assign the new ID instead. To take one away from a project, remove its ID from the project's list, or add it under the project's deny block. A connector you take away disappears from users' Connectors dialog the next time Knowledge Worker Agent starts, or when they select Refresh configuration.

Provide a connector

  1. Write a connector artifact: an mcp block with the server, and an sds block that says how users connect to it.
  2. Register and assign it.
Assigned connectors appear for users marked Provided by IT, and switched off. Each user turns on the ones they want. Don't set enabled in the artifact. It's removed, and a warning is logged.
The next time Knowledge Worker Agent starts, users who haven't set up a connector or model provider you assigned see it in New in your workspace. Give each artifact a description, one sentence on what it's for, so they know why to set it up. For the field, see Configuration repository.
If each user needs their own API key, set "type": "api-key" in the sds block. Users then add their key in the Connectors dialog. Never put a key in the repository.

Provide a model provider

For a complete example with a model you host yourself, see Use a self-hosted model provider.
  1. Write a provider artifact: a provider block that defines the provider and its models, and an sds block.
  2. In the sds block, choose who supplies the key:
    • "type": "managed": you provision the key, for example in a file. Give its location in secretRef.
    • "type": "user-key": each user adds their own key under Accounts.
  3. Under presets, name the models behind Default and Thinking. You can also name a small model for short background jobs, such as naming chats.
  4. Register and assign it.
  5. Set KWA_CENTRAL_CONFIG=true in the workspaces.
Without presets, Default and Thinking may not find a model.
How much the provider block needs depends on whether opencode already knows the provider:
  • A provider opencode knows, such as GitHub Copilot, Google Vertex AI, or Mistral's public API: give only the provider ID, a display name, and any model list limits. opencode supplies the package, address, models, costs, and limits. Adding npm, options, or models replaces its definition with a copy that goes out of date.
  • A private endpoint: define everything, including a cost and a limit for each model. Without them, every turn shows no cost and no context limit.
GitHub Copilot and Google Vertex AI keep their own sign-in. Don't add sds.auth to their artifacts, because it's ignored.

Limit the models users see

A provider's full model list can include models a chat can't use, such as embedding or audio models. To show only some, add opencode's whitelist array, or a blacklist array, to the provider block:
{
  "provider": {
    "mistral": {
      "name": "Mistral",
      "whitelist": ["mistral-large-latest", "mistral-medium-latest"]
    }
  }
}
  • Use bare model IDs, such as mistral-large-latest, not mistral/mistral-large-latest.
  • A model that opencode marks as deprecated can't be added this way. It's left out without a warning.

Provide agents, context, and skills

  • Agents: add an agent file (.md). Users see it under Provided by IT when they choose an agent.
  • Context: add a single Markdown file with guidance the assistant should always follow, such as a writing style. It's added to the instructions of every chat. Register each file on its own. A context artifact that points to a folder stops the whole run, and the workspace gets nothing.
  • Skills: add a folder with a SKILL.md file, plus any scripts it uses. Users see it in the Toolbox.
Artifacts are written to a folder chosen at startup, not to ~/.config/opencode. Don't put that path, or any fixed path, in an artifact. For how to write skills and agents that work wherever they land, see Write skills and agents for your teams.

Teach dictation your organization's names

  1. Write a vocabulary file: a Markdown table with the columns Term and Heard as.
  2. Register and assign it under vocabulary.
Dictation then gives the speech engine your terms as hints, and replaces the listed mishearings with the term. Unlike other artifacts, you can change a vocabulary file in place. Workspaces pick up the change at their next start.

Check that it worked

Knowledge Worker Agent writes one line to its log at startup. If the configuration was applied, the line shows the project and how many of each kind it wrote:
✓ Central configuration: project proj_sales → … (mcp=1 agents=0 context=0 skills=0 provider=0 vocabulary=0)
If a variable is missing, the line starts with ℹ, says skipped, and names the variable. Warnings start with ⚠. For other messages, see Troubleshoot Knowledge Worker Agent.
The same is shown in the workspace, without the log. In Settings > Diagnostics, the Configuration tab shows the project, the repository, the commit in use, when it was last applied, what was applied, and any warnings. If the latest attempt failed, a warning says so, and that the earlier configuration is still in use.

Apply a change without a restart

The configuration is applied when Knowledge Worker Agent starts. To apply a change to the repository in a running workspace:
  1. In Knowledge Worker Agent, select Settings (the gear icon) at the bottom of the sidebar, then Diagnostics.
  2. Select the Configuration tab, and select Refresh configuration.
The button shows each step while it runs. Knowledge Worker Agent fetches the repository, applies it, and reloads the models, agents, model providers, connectors, and skills. If the refresh fails, the configuration in use stays as it was.
Refresh configuration isn't available while Knowledge Worker Agent is starting, or in a workspace with no project or configuration repository set.