Configuration transfer between environments
DioscHub can export its admin configuration from one environment and import it into another — the staging-to-production promotion, or seeding a new environment from an existing one. It moves configuration, not secrets and not content: credentials never leave the source, and knowledge-base files stay behind. This page covers what transfers, how the flow works, and the manual steps you own after an import.
What transfers, and what does not
Section titled “What transfers, and what does not”Export covers these kinds of configuration:
| Section | What it carries |
|---|---|
| System Settings | The platform settings, as one item named platform: rate-limit defaults, compaction, the files section (upload limit, storage quota, retention and the file type rules) and the other tunables. The embedding credential link is stripped, and the conversation retention window is left out. |
| Models | Model definitions (the provider credential link is stripped — see below) |
| Toolsets | Toolset definitions |
| MCP instances | MCP server registrations (static auth config stripped) |
| MCP tool approval configs | Which tools require consensus, per server |
| Knowledge bases | The knowledge-base shell only — name, description, active flag |
| Assistants | Assistants, with their roles, sitemap, and knowledge links nested underneath |
Roles and sitemap entries are not separate sections; they travel nested under their assistant.
What is deliberately not transferred:
- Credentials — provider API keys, MCP server auth, and any stored secret. These never leave the source environment. An import keeps the target’s stored MCP server credential, so it refuses a file that would move an MCP server with a stored credential to a server URL on another origin, naming the server. Change that URL on the server’s page in the target and enter the secret again there.
- Knowledge-base files — only the knowledge-base shell travels; you re-upload the files in the target.
- Content and runtime data — chat sessions, history, usage, and files.
- The conversation retention window — its period, the pinned rules and waiting for BI. An import never sets or changes the target’s window, so a file can’t shorten it; set it on each environment.
- Admin access — the global site/CORS configuration, admin users and their permissions, and admin API keys are not part of a configuration transfer.
Because credentials and content stay behind, a configuration transfer is not a backup. For that, see Upgrades, backup & DR.
How it works
Section titled “How it works”The flow is export → analyze → review → apply, done in the admin portal:
- Export produces a JSON document. You pick the sections and items to include.
- Analyze compares that document against the target environment and shows a diff.
- Review lets you cherry-pick exactly which changes to apply, down to individual roles and sitemap entries.
- Apply writes the selected changes in a single transaction. A fatal error rolls the whole import back, leaving the target unchanged. Items that are individually skipped — for example an approval config whose MCP server was not also imported — are reported without blocking the rest, so the changes that did apply are committed.
Matching across environments is by a stable name or identifier, not by internal database ID, so an assistant or toolset called the same thing in both environments is recognized as the same entity.
An import only adds and updates the items you select. It never deletes a top-level item in the target that was not in the export.
Problem reports travel
Section titled “Problem reports travel”The problem reports switches are part of the configuration, at two levels:
- Each assistant carries
problemReportsEnabled(trueorfalse). An assistant that follows the default (null) exports without the field. - The deployment default is
problemReports.defaultEnabledin the System Settings itemplatform. The rollout banner’s acknowledgement (bannerAcknowledgedAt) never travels: a file can neither acknowledge nor un-acknowledge the target’s banner.
An export made before this release, or by a source that follows the default, has no such field, and importing
it leaves the target’s current value unchanged: an existing assistant keeps its own setting and the target keeps
its default. A new assistant created by an import with no field follows the target’s default (so
PROBLEM_REPORTS_DEFAULT=off on the target holds). An explicit null in the file puts an assistant back on the
default; a value that is not true, false or null is not applied and is reported. Whether reports are actually
offered still needs the problemReports license on the target.
Webhook sinks, problems and reports are content and credentials, not configuration: they do not travel.
Per-entity behavior you should know
Section titled “Per-entity behavior you should know”The import semantics differ by entity in ways worth knowing before you promote to production:
- Assistants are matched by name and updated in place; a new name creates a new Assistant.
- Roles and sitemap entries are matched by name (role name, sitemap path) and updated in place. Entries that exist only in the target are left untouched unless you explicitly mark them for deletion during review. Importing does not wipe roles or sitemap you did not touch.
- Models land with no credential link when created for the first time — you re-link the provider API key in the target. Re-importing an existing model never overwrites a credential link it already has.
- MCP instances import their registration but not their auth config; a newly created instance has no credentials until you add them in the target, and re-importing an existing one keeps the target’s auth config.
- MCP tool approval configs are matched per tool. If a config references an MCP server that was not also imported, it is skipped and reported rather than failing the import.
- Knowledge bases import as an empty shell; re-upload the files in the target.
- System Settings replace the target’s settings row as a whole, with the
filessection checked rather than trusted: its limits are clamped to their bounds and unknown keys are dropped (see System settings). - File type rules (
files.typeRules) are validated on import by the same rules as System → File types:- At analyze, invalid rules, or two rules with the same key (extension or MIME type), are listed as a warning on the System Settings section.
- At apply, the same problems fail the System Settings item: none of the target’s settings are changed, the error is reported, and the other sections still apply.
- Valid rules are stored in their normalised form (lower-case keys, no leading dot, trimmed hints).
- An export with no
typeRules— one made before file type rules existed — keeps the rules the target already has, instead of clearing them. - Rules apply to files uploaded after the import. Re-index files in the target to re-classify ones that are already stored (see Re-classify stored files).
After you import
Section titled “After you import”Because credentials and files stay in the source, a freshly imported environment is not yet operational. Work through:
- Re-link every model’s provider API key.
- Add auth config to every MCP server that needs it.
- Re-upload knowledge-base files.
Permissions
Section titled “Permissions”Configuration transfer is gated on the config:transfer admin permission. An admin without it cannot
export or import. The permission exists only on a license with the configTransfer feature (Enterprise),
and it is not needed for the File types page itself: managing rules in one environment needs
file-types:manage, on every tier.