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 six kinds of configuration:
| Section | What it carries |
|---|---|
| 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.
- 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.
- System-level settings — 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.
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.
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.