Central configuration

Last published : Nov 09, 2026
Central configuration lets an administrator decide, in one place, what every workspace in a project starts with. This page explains the ideas behind it: what it provides, what stays with users, and why some choices are made the way they are.
Related information
About

One repository, many workspaces

Without central configuration, each person sets up their own workspace. They connect providers, add connectors, and write agents themselves. That works for one person. For a team, it means everyone repeats the same setup, and no two workspaces match.
Central configuration moves that setup into a repository. The repository holds building blocks, called artifacts:
  • Connectors
  • Model providers
  • Agents
  • Context, such as a writing style
  • Skills
  • Dictation vocabularies
A control file, assignment.jsonc, says which artifacts each project gets. When Knowledge Worker Agent starts in a workspace, it reads the repository, finds the workspace's project, and writes that project's artifacts into its own configuration folder.
Defining an artifact and deciding who gets it are separate steps. One writing style can be defined once and given to several projects, and moving a connector from one project to another is a one-line change.

Provided, not imposed

Central configuration makes things available. It doesn't take choices away from users where the choice is theirs:
  • Connectors arrive switched off. Each user turns on the connectors they want. An artifact that tries to switch a connector on or off has that setting removed. Otherwise the switch in the Connectors dialog would stop working, one way or the other.
  • Users keep their own configuration. Knowledge Worker Agent writes assigned artifacts to a separate folder, and never to the user's own configuration. The user's own agents and connectors stay as they are. Assigned context is added to the user's own instructions, not put in their place.
  • Built-in connectors that users rely on stay. With KWA_CENTRAL_CONFIG on, the built-in connector catalog isn't installed, but a built-in connector a user turned on, signed in to, or changed is kept.
  • Credentials stay personal. A connector or provider that needs a key per person asks each user for it. No key is stored in the repository.
Some things are the administrator's to decide:
  • Assigned connectors can't be edited or removed by users, only turned on or off. They're marked Provided by IT.
  • Assigned model providers replace the built-in ones when the workspace is under central management. Offering both would leave no clear rule for which provider's Default model wins.

Immutable artifacts

Each artifact ID stands for one version of an artifact. To change a connector, you add the new version under a new ID and point the project at it. Going back means pointing the project at the old ID again.
This keeps every project's configuration traceable: an ID always means the same thing. Vocabularies are the exception. They're word lists that can't break a workspace, so they can be edited in place.

When it's applied

The repository is read when Knowledge Worker Agent starts, and when someone selects Refresh configuration in Settings > Diagnostics. The assigned artifacts are rewritten each time, so an artifact removed from a project is gone after the next start or refresh, not left behind.
The new configuration is built beside the one in use and swapped in only when it's complete. If the repository can't be reached, or a refresh fails, the configuration in use stays as it was, so a network problem doesn't leave a workspace without its configuration. For the steps, see Apply a change without a restart.

Not a security boundary

Central configuration decides what a workspace is given. It doesn't stop a workspace from reaching other services. A user can still add their own connector, for example. A deny entry is a convenience for leaving an artifact out, not a control.
To restrict what a workspace can reach, use controls outside Knowledge Worker Agent. An AI Gateway can limit which model providers and models a workspace uses, and SecurSpaces controls which other services it can reach. Central configuration sets what a workspace starts with, and those controls set the limit. For more information, see Configure AI Gateway routing.
Context is guidance, not enforcement. An assigned context file is always loaded, but whether the model follows it is best effort.