Upgrade Notes
Use this page when upgrading an existing deployment across a release that needs operator action. Each section names the change, what to do before or after the upgrade, and what does not carry over. Always back up configuration and persistent storage before replacing the running version, and never run two backend versions against the same storage at once.
Upgrading to the filesystem toolkit
The file and coding tools are now one toolkit, filesystem, with the functions coding had.
Configs that list file or coding in tools, worker_tools, contacts.tools, or MINDROOM_SANDBOX_PROXY_TOOLS load unchanged.
An agent whose tools, together with the defaults.tools it takes, name the toolkit more than once gets one toolkit only when none of those entries has settings and their defer and initial flags match; otherwise the config fails to load and names both entries, so keep one entry named filesystem with the settings you want.
Nothing saved for the old tools is translated, so before upgrading, change what the list below names:
- A
fileentry with a setting of the earlier toolkit fails config loading and names the replacement:enable_save_file,enable_replace_file_chunk,enable_read_file,enable_read_file_chunk,enable_list_files,enable_search_files, andenable_search_contentare removed and, where they were off, becomeexclude_toolswithwrite_file,edit_file,read_file,read_file,ls,find_files, andgrep; removeall, and setenable_delete_file: trueonly ifallhad turned deletion on and you still want it;max_file_length,max_file_lines,line_separator,exclude_patterns, andexpose_base_directoryhave no counterpart; andinclude_toolsorexclude_toolsmust name the new functions. tool_approvalrules fail config loading when the first rule that matchedsave_file,replace_file_chunk,read_file_chunk,search_files, orsearch_contentis not also the first rule that matches its replacement, naming that rule and the new function; alist_filesrule loads, becausepythonstill has that function, and no longer coversls.- Settings saved from the dashboard for
fileorcodingstop the agent'sfilesystemtoolkit from loading, and its room workspace from being listed, until you delete them, saving any you still want underfilesystem; settings of the earlierfiletoolkit saved underfilesystemstop it the same way. - A contact's tools, a
dynamic_workflowallowed_toolsentry, a saved workflow, a saved subagent profile, the tools chosen for a created agent, and a subagent started before the upgrade that namefileorcodinggrant nothing: namefilesystemin them, and start a new subagent instead of continuing the old one. - A
scriptallowed_toolslist that namesfileorcodingmakes every script launch fail until it namesfilesystem. - A background tool job that an agent started with
fileorcodingdoes not resume after the upgrade, so let running jobs finish first. - Upgrade workers and the sandbox runner together with the primary.
Upgrading to a shell that needs a worker
The shell tool now refuses commands in the MindRoom process, so an agent with shell and no worker, such as one an earlier mindroom config init created with worker_tools: [], gets an error on every shell call.
To keep running its commands in the MindRoom process, add allow_shell_without_worker: true under defaults: in config.yaml; otherwise route shell to a worker as in Sandbox Proxy Isolation.
Upgrading from Agent Vault
MindRoom no longer supports Agent Vault; Agent Keys injects credentials into worker egress instead, and secrets stored in Agent Vault do not carry over.
Before upgrading, remove agent_vault_access from agents' tools: lists and defaults.tools, because a config that still lists it fails to load, and give agents that need brokered credentials the egress_credentials tool.
In runtime chart values, enable the egress broker and delete workers.kubernetes.agentVault, approvedEgress.parentProxy.enabled, approvedEgress.parentProxy.host, and approvedEgress.parentProxy.port, which the chart now ignores; approvedEgress.parentProxy.bypassDomains still applies to the broker chain.
A helm upgrade of a release that ran the chart-managed Agent Vault server deletes that server, its Jobs, and its data claim, so first back up the volume and its bootstrap Secret if you still need the stored secrets.
Helm leaves behind the CA ConfigMap (workers.kubernetes.agentVault.workerCaConfigMapName) and the admin token Secret (default agent-vault-access-admin) that the bootstrap Job created, so delete them yourself, and remove the archived agent-vault-bridge plugin from plugins: if you use it.
Upgrading to shared team memory
Earlier releases kept a copy of each team's memory in every member's storage directory; the first start after this upgrade merges those copies into team memory under team_memory/ before any agent comes online, and removes each copy it merged from its member; the exceptions below stay where they are.
Each member had extracted every team turn on its own, so each turn keeps the member's extraction that holds the most facts, as a team turn now writes one; a turn only one member stored stays, and file team memory keeps every MEMORY.md entry once.
Mem0 copies merge from the agents the config lists with Mem0 memory, the only stores they were read from; to keep the team memories of an agent you switched to file or none for now, switch it back to mem0 before upgrading.
A member's team file copy holding anything MindRoom did not write, such as a hand-written line or another file, stays where it is, no longer read, and startup logs a warning starting with Left with its path; to keep a note from it, add it to the team's MEMORY.md as a - [id=<unique id>] <note> line, since team memory finds only such entries.
A member's Mem0 store holding a link or special file, or one Chroma cannot read, is not merged either, and its warning also starts with Left; its team memories stay there, no longer read.
Only Mem0 team memories of the configured embedder merge; those an earlier embedder wrote, which the runtime no longer read, stay with a Left warning, as does a memory whose embedding size the configured embedder never gives.
A storage error while writing team memory stops startup before any member's Mem0 copy is removed, and the next start merges the rest.
The first start installs Chroma for this when any agent the config lists has a Mem0 store; with MINDROOM_NO_AUTO_INSTALL_TOOLS=1 and no chromadb extra, the Mem0 copies stay until the first start with Chroma.
With any embedder other than OpenAI's own API, such as a local or Ollama embedder or an OpenAI-compatible server set as host or through OPENAI_BASE_URL, the first start asks the embedder once for the size of its embeddings, and the Mem0 copies wait for a start whose embedder answers; after fixing the embedder, restart MindRoom to merge them.
An older release does not read team_memory/; after going back and upgrading again, delete tracking/team_memory_merged.json before the start so the copies that release wrote merge too.
That start also checks again every copy a Left warning named, so first remove any of them whose memories you do not want back.
Upgrading to progress kept in conversation order
This upgrade needs no action: conversation databases convert at the first start without a backup, and memory auto-flush, knowledge-graph ingestion, and the exploration automation convert their progress when they next read each conversation.
Going back from progress kept in conversation order
The release before this one reads the converted databases, but its memory auto-flush and knowledge-graph ingestion then fail on every pass for each agent or graph whose progress converted, logging Memory auto-flush failed for an agent or Knowledge graph ingestion failed for an agent.
To go back, stop MindRoom, then restore tracking/memory_auto_flush.json and each knowledge_graph/ingestion/<graph>.json under the storage root from a backup taken before the upgrade, or delete them.
Without those files, auto-flush starts again with the turns after the next start, and ingestion reads the conversations active within knowledge_graph.ingest.backfill_days again, which pays for that extraction again.
That release's usage reports also leave out the usage recorded while this release ran.
Upgrading to one owner per conversation database
The first start after this upgrade converts every conversation database once more before any agent comes online, as the conversation storage v2 upgrade did, so that each records the agent, team, or internal usage store it belongs to.
A team's database that holds no conversation yet converts when that team next uses it instead.
Each converted database logs one conversation_converted record (see Events).
Conversation history, compaction summaries, session state, pending tool approvals, and usage records carry over.
Before upgrading to one owner per database
Make sure each disk that holds conversation databases has free space of about twice the total size of their .db files.
A database still in the Agno layout, which the conversation storage v2 upgrade never converted, converts straight to this layout and needs the free space that section gives instead.
A database whose directory lacks the space it needs is not converted: startup logs conversation_conversion_skipped_store for it, and every use of it fails with an error naming the database and the bytes it needs until you free the space.
A deploy that rolls back on its own, such as helm upgrade --atomic, starts the older release on converted databases, which then moves them aside (see the next section).
Going back to an older release
Before converting a database, MindRoom copies it byte for byte beside it and never deletes that copy: to <name>.db.pre-storage-v4 for a database the conversation storage v2 upgrade already converted, and to <name>.db.pre-storage-v2 for one still in the Agno layout.
A crash or restart during the upgrade leaves the database being converted unchanged, and the next start converts it.
The only way back is to stop MindRoom, replace each <name>.db with the copy this upgrade made of it, delete any <name>.db-journal beside it, and start the older release.
When a database has both backups, the copy this upgrade made is the newer file.
Everything written since the upgrade is lost: replies, summaries, session state, approvals requested since then, and usage records for that period.
An older release started on converted databases without restoring the backups archives each agent's or team's sessions/ directory, backups included, as Incompatible session databases describes; move the backups back out of that archive and restore them as above.
Going back below conversation storage v2 from a database that has both restores its .pre-storage-v2 backup instead, as Downgrading describes.
Once you are sure you will not downgrade, delete these backups.
Upgrading to checked model references and per-agent workspaces
A config whose agent, team, router, room, thread-summary, or enabled voice model names no model under models now fails to load instead of failing at the first reply, so run mindroom config validate before upgrading and add or rename the missing models; a config with agents and no router.model needs a model named default.
Every agent now has its own workspace, and a shared agent whose worker_scope is user or user_agent works in it instead of each worker's own scratch directory, so files those workers kept in their scratch directories are no longer the agent's working directory.
Make such an agent private to keep each requester's files apart.
Upgrading from MCPTools plugin toolkits
MindRoom no longer runs plugin toolkits that subclass Agno MCPTools (see MCP servers).
Before upgrading, configure each such server under mcp_servers: in config.yaml as MCP describes, and replace the plugin tool's name with mcp_<server_id> in agents' tools: lists and in defaults.tools.
The community plugins are not affected.
Upgrading to conversation storage v2
The first start after this upgrade converts the conversation database of every agent and team, private instances included, and the internal usage database under system/, to a new layout before any agent comes online.
Each converted database logs one conversation_converted record (see Events).
The process stays live but becomes ready only after the conversion and the rest of startup finish; Health & Readiness says what each endpoint answers meanwhile.
The conversion is one-way, and downgrading afterwards is not supported.
Before upgrading
Check that every startup probe asks /api/health, as the bundled Helm charts do and Health & Readiness requires.
A deploy that rolls back when readiness times out, such as helm upgrade --atomic with its default 5-minute timeout, can roll back mid-conversion and start the older release on converted databases (see Downgrading), so raise the timeout or drop --atomic for this upgrade.
Make sure each disk that holds conversation databases, under the storage directory or MINDROOM_SESSION_STORAGE_PATH, has free space of about two and a half times the total size of their .db files.
A database that no release since v2026.10.341 has opened can still hold Agno 2 run blobs or the compaction archive, which the conversion copies first, so it needs up to about three and a half times its size.
A database whose directory lacks the space it needs is not converted: startup logs conversation_conversion_skipped_store for it, and every use of it fails with an error naming the database and the bytes it needs until you free the space, after which its next use converts it.
What carries over
Conversation history, compaction summaries, pending tool approvals, and usage records carry over.
Before converting a database, MindRoom copies it byte for byte to <name>.db.pre-storage-v2 beside it and never deletes that copy.
A stored run whose data cannot be read is left out of the converted database, logged as conversation_run_left_out with its run ID, and kept in the backup.
A crash or restart during the upgrade leaves the database being converted unchanged, and the next start converts it.
Right after converting a database, MindRoom compacts it to return the space its old tables used, when its directory has free space of about twice the converted data.
Without that space the file keeps it until later writes reuse it; with MindRoom stopped, sqlite3 <name>.db VACUUM returns it.
Downgrading
The only way back is to stop MindRoom, replace each <name>.db with its <name>.db.pre-storage-v2 backup, delete any <name>.db-journal beside it, and start the older release.
Everything written since the upgrade is lost: replies, summaries, session state, approvals requested since then, and usage records for that period.
The older release drops messages redacted since the upgrade from the restored history before it next replies in that conversation, but edits made since the upgrade are not applied again, so the earlier reply to an edited message can return to the agent's history.
An older release started on converted databases without restoring the backups archives each agent's or team's sessions/ directory, backups included, as Incompatible session databases describes; move the backups back out of that archive and restore them as above.
Upgrading again converts each restored database again and writes a new backup.
Once you are sure you will not downgrade, delete the .pre-storage-v2 backups.
Upgrading to OpenAI SDK 3
OpenAI-compatible and Claude model requests, and the other OpenAI SDK requests Model Configuration lists, now verify certificates against the operating system's trust store instead of certifi's bundle.
The published images include system CA certificates.
On a host without them, install them (for example the ca-certificates package) before upgrading, or point SSL_CERT_FILE at a complete CA bundle, such as certifi's cacert.pem with any private CA appended.
Upgrading to durable reply records
Upgrade while no agent is replying. Stop the previous backend once in-progress replies have finished, and decide pending tool approvals first: the upgrade cancels every approval of a paused reply still waiting or not yet resumed, while approvals of scheduled calls are kept. A cancelled approval's card may stay visible, but clicking it does nothing, its reply keeps what it showed, and the request is not answered, so resend it if needed. A reply that was still streaming when the previous backend stopped may be answered again after the upgrade, sometimes in a new message, and a tool it had already run can run again, so check the room before resending that request.
Upgrading to Nio 1.0
Existing deployments upgrade automatically during normal startup.
Stop the previous backend, install the new release, and start it with the same configuration and storage root.
No journal archival, database reset, or mindroom journal adopt command is required.
If you customized MINDROOM_MATRIX_SYNC_CACHE_WRITE_GRACE_SECONDS, replace it with MINDROOM_MATRIX_INGESTION_GRACE_SECONDS.
What the automatic migration preserves
The event journal is upgraded in place on both SQLite and PostgreSQL, keeping message history, redactions, and handled-turn records, so restarts do not produce duplicate replies. Configuration, credentials, workspaces, memories, knowledge stores, and agent sessions are untouched. Matrix accounts, device IDs, encryption keys, and device trust remain intact.
What does not continue
Replies and tool approvals left unfinished before the upgrade are abandoned and do not resume. An old approval card may stay visible but cannot be approved. A tool action that already ran is not undone, so check its result before retrying it manually.
On first startup each room's existing history is loaded as context only and does not trigger replies or commands, including encrypted messages whose keys arrive later.
Messages sent during the downtime can therefore stay unanswered; resend any request you still want handled once startup completes.
Later messages are handled normally.
The old tracking/room_member_joins.json file is no longer read, and existing room members are not onboarded again.
Device recovery after the upgrade
Normal restarts reuse the existing Matrix device. If the homeserver reports a soft logout, MindRoom renews credentials for the same device with the configured authentication method, without losing pending work or encryption keys.
MindRoom never replaces a device automatically. If the device store is missing, restore the deployment's matching storage backup before restarting. A hard logout, a deleted server device, a changed returned identity, corrupt storage, or an unknown storage format requires operator recovery. Clearing the journal or the crypto directory is not a supported repair, because a Nio 1.0 device session is bound to its journal. Preserve the failed deployment's state while recovering it, because pending input and attempted deliveries may still need reconciliation.
Private storage migration
Private storage created by v2026.9.32 or earlier uses older requester directory names. The first primary startup of a release with this migration moves every verified private scope to its current path before accepting traffic. Current and empty storage need no migration and trigger no worker checks.
Before upgrading
- Pause new requests and scheduled work, then drain active responses, tool calls, shell commands, and background processes. Stop every writer through the deployment lifecycle, including the previous primary, independent controllers, supervised processes, managed Docker or Kubernetes workers, and external runners. Disable worker creation, restart policies, and external reconciliation until the migration finishes, because MindRoom cannot fence older binaries or the control plane.
- Remove managed Docker worker containers, including stopped ones, while keeping their host state and credential directories.
For Kubernetes, delete every worker Deployment and ReplicaSet and wait until every worker Pod, including terminating Pods, is gone; scaled-down controllers still block migration.
The check covers every resource labeled
mindroom.ai/worker-idin the configured worker namespace, whatever primary owns it, so deployments sharing that namespace must coordinate this quiet window. - Back up primary storage, session storage, and worker state together while writers are stopped.
- Mount the original volumes at the same configured primary and session paths.
When
MINDROOM_SESSION_STORAGE_PATHis set, make sure that volume is available before starting. - Start the new primary with worker creation still disabled externally. When a move is needed, startup checks that no workers exist before changing anything; it never stops or deletes workers itself. A worker API failure, missing permissions, or remaining workers stops startup.
- Resume admission, scheduling, and worker creation only after startup succeeds.
Kubernetes primary service accounts need list on deployments and replicasets in the apps API group and on pods in the core API group, within the configured worker namespace.
The runtime chart's worker-manager Role includes these permissions, so apply the updated Role before starting the upgraded primary; externally managed RBAC must grant the same.
Static external sandbox runners must be stopped separately.
For the migration startup, remove MINDROOM_SANDBOX_PROXY_URL from the primary configuration after stopping the runner, because a configured external runner blocks the migration.
Restore the setting and restart the runner after the migration finishes.
What changes
Files, databases, credentials, workspaces, and histories keep their contents. Each old directory name stays behind as a relative symlink to its new directory, so absolute workspace paths and script shebangs keep working. Keep these links when backing up and restoring the volumes; they are not recreated if lost. Worker credential directories are not moved.
Private scopes without an owner record, which older releases could create, are left in place with the warning Preserving private scope without an owner record; not migrating.
They are not attached to the requester's new private scope.
Recover that history manually only after independently verifying its owner, with all writers stopped.
While a move is pending, its scope contains .mindroom-private-storage-migration.json, which holds private owner information; never delete or copy it.
Interrupted or rejected startup
Restart the primary with the same mounted data and configured paths to resume an interrupted migration; remounts that keep the same directories are fine. Do not create destination directories or start other writers during recovery.
An entry under private_instances whose ownership cannot be verified is left untouched with the warning Leaving an invalid private storage entry untouched; not migrating, and startup continues.
Startup stops with an error starting with Private storage migration: for conflicts it cannot leave aside, such as a missing or overlapping volume, two scopes claiming the same owner, session-only data without a primary scope, or nested mounts.
Correct the reported conflict with all writers stopped, then restart.
Once every verified move finishes, startup writes tracking/private_storage_migrated.json and later starts skip the migration.
To migrate an entry that was left untouched, fix it with all writers stopped, delete that file, and restart through the quiet window above.
There is no migration CLI or automatic rollback. To return to an older release, stop all writers and restore the coordinated backups together before starting it.
Membership Access Migration
See Access Control for the membership access schema.
Loading a single-file configuration that still uses retired access fields converts it automatically.
MindRoom validates the result, replaces config.yaml, removes the retired fields, keeps explicit new-schema values, and saves the original once as config.yaml.pre-membership-access.
The rewritten YAML loses comments and hand formatting; the backup keeps both.
When config.yaml is a single-file Docker bind mount that cannot be replaced, loading stops and asks you to run mindroom config migrate --path <host-config.yaml> on the host.
If the migration is rejected, replace non-concrete identity grants with concrete Matrix user IDs, replace unresolved room IDs or aliases with managed room keys, and remove authorization.agent_reply_permissions entries for agents or teams that no longer exist, then retry.
Configurations that use !include are not migrated.
When retired access fields and !include appear together, loading fails with Automatic access migration does not support !include configurations and changes no files.
Remove the includes or migrate the combined configuration by hand before retrying.
Upgrade and reset limits
Smaller changes that need operator action:
- Host browser files: primary-process browser profiles live in each agent's state root, and
<storage>/browser-profilesis not read; sign in again, then delete that directory. Default host browser screenshots, PDFs, and downloads live inbrowser/in each agent's state root, anduploaddoes not accept files left in<storage>/browser; move any you still need into the agent workspace, then delete it. - Browser egress proxy: Chromium in the host, headless worker, and Computer browsers and in
crawl4aitunnels every connection, plain HTTP included, through the configured egress proxy with HTTPCONNECT. The proxy must allowCONNECTto ports 80 and 443, and for the primary also to IP addresses; the chart-managed approved egress proxy needs the minimum proxy image version. In a sandbox runner, set every proxy variable, or onlyall_proxy, to the same HTTP(S) proxy, or the browser does not start. See Egress Proxy for Browsers for the full rules. - Mem0 history file: Mem0 memory keeps its history in
mem0/in each agent's state root, and stored memories carry over; MindRoom does not read thehistory.dbin Mem0's own directory (~/.mem0/, orMEM0_DIRwhen set), which can hold the text of deleted memories, so delete that file unless an agent uses themem0tool without an API key, which keeps its history there.mem0is now a reserved name, so an agent whoseprivate.rootstarts withmem0fails config load until you rename it. - Boolean tool settings: stored tool config values for boolean fields, including credential seeds read from environment variables or files, must be JSON booleans, JSON
null, or exactlytrueorfalse; any other value makes the tool fail to load with an error naming the field. - Retired Agno settings and unsupported model keys: when you upgrade, delete
learningandlearning_mode,compress_tool_results, and thewebsitetool'sknowledgeoption fromconfig.yaml, since each fails config load. Configs created by oldermindroom config initruns setlearning: falseon themindagent. Thelearning/<agent>.dbdatabases that Agno Learning left under agent state roots are unused, and you can delete them. Also delete everyextra_kwargskey a model's provider does not accept, such as the retired Agno settingretriesor a misspelled key, on every model, including models no agent uses; Extra Kwargs lists the accepted keys. - Tool settings that took Python objects: delete these settings, which no config value could supply, from every tool entry in
config.yaml, since each fails config load:db_engineandtablesofsql,connectionofpostgres,connectionandconfigofduckdb,duckdb_connectionandduckdb_kwargsofcsv,obbofopenbb,safe_globalsandsafe_localsofpython,reddit_instanceofreddit,knowledgeofwikipedia,sandbox_optionsofe2b, andworkspace_config,connected_account_ids,metadata,processors, andlogging_levelofcomposio. Values saved for them in the dashboard are ignored. - Unknown config keys: every section of
config.yamlexcept free-form maps, such as a plugin'ssettingsandmemory.llm.config, rejects keys MindRoom does not define, so a misspelled or leftover key, such as one undermemory,models,knowledge_bases,voice,router,plugins,authorization, or an agent'sprivateorcompaction, fails config load withUnknown keyeven when nothing uses it; before upgrading, run the new release'smindroom config validateand delete or correct each key it names. - Sandbox runner release: a
static_runnersandbox runner from a release with another worker protocol, such as a Composesandbox-runnerservice that was not pulled again, is refused and the calls routed to it fail, so upgrade it together with the primary (see Keeping worker versions matched). - Model providers: a model whose
provideris not one of the supported providers fails config load, even when no agent uses it, somindroom runand the dashboard do not start until you fix or delete that model inconfig.yaml; this includes models saved earlier with Together, Mistral, Perplexity, Cohere, or xAI. - Model names: a model key under
modelsmay contain only letters, digits,:,_, and-, so a key such asgpt-6.1fails config load even when no agent uses it, andmindroom runand the dashboard do not start until you rename it, as Model Config Fields describes, and update every reference to it. - Restart resume setting:
defaults.auto_resume_after_restartis removed and fails validation, so delete it fromconfig.yaml; a reply interrupted by a restart always continues in the same message. - Delegation records: a delegation still running during the upgrade finishes normally, but its workspace
run.json,events.jsonl, andtranscript.mdstop updating. - Background tool jobs on by default: a config without
background_tool_jobsturns on background jobs, so a tool call can continue in the background and most gated calls ask from their job instead of pausing the reply until the decision; to keep replies waiting for every call and pausing for approvals, setbackground_tool_jobs.enabled: falseand restart MindRoom. Every reply of an agent whose tools offer a function namedjobfails while background jobs are on, because that name is reserved; rename that function or turn background jobs off. - Pending tool approvals after going back: once this release has opened a conversation, an earlier release cannot resume a reply in it that waits for a tool approval, and approving it there fails; answer pending approvals before going back, or ask again afterwards.
- Knowledge index state: the first start converts each semantic knowledge base's index in place, and older releases cannot read the converted index, so going back to one rebuilds every semantic base from scratch, embedding every file again, and its search is unavailable until that rebuild finishes.
- MCP gateway and shared agents: the MCP gateway no longer offers agents whose worker scope is
sharedor unset, so their users lose gateway access to them and saved selections of them stop working. To restore an agent, setmcp_gateway_shared_credentials: trueon it or give itworker_scope: useroruser_agent. - Retired prompt overrides: a
promptsentry forDEFAULT_UNSEEN_MESSAGES_HEADER,INTERRUPTED_PARTIAL_REPLY_HEADER,MIXED_PARTIAL_REPLY_HEADER, orPREVIOUS_CONVERSATION_THREAD_HEADERfails validation as an unknown prompt, so delete it fromconfig.yaml; no prompt rendered these headers, so removing them changes no text a model reads. - Dedicated workers: the upgrade replaces every Docker and Kubernetes worker once on its next use, which ends background shell commands running in it. Kubernetes background scripts still running during the upgrade are interrupted when MindRoom starts again instead of resuming; start them again.
- Credentials from the environment: the first start, or
mindroom doctor, deletes the credential files earlier releases copied from provider-key variables,OLLAMA_HOST,GITHUB_TOKEN,EMBEDDER_API_KEY,GOOGLE_APPLICATION_CREDENTIALS, and credential seeds; MindRoom now reads those values from the environment at each start (see Credentials from the Environment). Before upgrading, set again any such variable you removed after MindRoom imported it, or save that credential in the dashboard, or the key stops working; startup logs each removed service whose variable is no longer set. - Docker worker config: Docker workers get the config MindRoom has applied, and
MINDROOM_DOCKER_WORKER_HOST_CONFIG_PATHonly says where that config's directory is on the Docker host; a separate file at that path is no longer read, so move any worker-only settings intoconfig.yaml. - Public address setting:
MINDROOM_BASE_URLis removed andmindroom runrefuses to start while it is set, so before upgrading, move its value toMINDROOM_PUBLIC_URLunless that is already set, and delete it. - Room references:
rooms,room_thread_modes, an automation'sroom, the keys ofroom_models, and the keys ofroom_thread_summary_modelsother than agent and team names must name a room MindRoom can find, so a#alias of a room MindRoom did not create, or a room key no agent, team, or top-levelroomslists, now fails config load andmindroom runrefuses to start. Run the new release'smindroom config validateand replace each reference it names with a room key or the room's!room ID, as Rooms describes.
Compaction History
Downgrading below the release that keeps compacted runs in the conversation database beside their summaries is unsupported: older releases replay every compacted run again, and compaction state they write is never adopted again.
When upgrading from v2026.9.314 or earlier, runs that those releases deleted during compaction are not recoverable. Summaries compacted by those releases record no per-run provenance, so redacting an event they may contain still clears that conversation's summaries and all of its runs.
Workspace-only worker mounts
From v2026.9.327, dedicated Docker and Kubernetes workers mount only agent workspaces. Drain worker activity before upgrading, because the upgraded primary stops every older worker before serving, ending its tool calls, shells, background scripts, and CLI sessions. Until those workers are gone, startup fails and the primary restarts, so the Docker daemon or Kubernetes API must be reachable. Upgrade worker images together with the primary, because Docker and Kubernetes refuse worker images from older releases. Rolling back to v2026.9.326 is safe when the Docker and Kubernetes worker images roll back with the primary; upgrading again stops those workers at startup.
Before upgrading, check two limits:
private.rootcannot start with a name the primary writes beside the private workspace, listed under Private Fields; such a configuration fails validation, so rename the root first.- Knowledge files above 64 MiB are left out of every knowledge base, including operator-managed ones, and the next refresh removes their existing vectors; find them with
find <knowledge folder> -type f -size +64M.
Older workers could write agent state roots, so after the upgrade check those roots for links they may have planted, running each command once with GNU find:
find "$STORAGE/agents" -mindepth 2 -type l -print -o -type d -regex "$STORAGE/agents/[^/]*/workspace" -prune
find "$STORAGE/private_instances" -mindepth 2 -type l -print -o -type d -regex "$STORAGE/private_instances/[^/]*/\([^/]*\)/\1_data" -prune
find "$STORAGE/agents" "$STORAGE/private_instances" -type f -links +1 -print
The first two commands skip links inside workspaces, which belong to the workers, and the verified old-name aliases directly below private_instances.
Remove every link they print, including a workspace that is itself a link, and inspect hard-linked files for data copied out of another instance.
The second command assumes the default private.root of <agent>_data.
When some agents set another root, pair every private agent with its root, default ones included, in one alternation such as -regex "$STORAGE/private_instances/[^/]*/\(notes/notes_data\|mail/inbox\)"; separate runs per root would print other agents' workspace links, and roots listed without their agents would skip same-named directories under other agents.
Config-free runners and workers
The static_runner sidecar and dedicated Kubernetes workers do not mount the primary's config; they receive the agent settings they need with each request.
The runtime chart's workers.kubernetes.configMapName, configKey, and configPath values and the matching MINDROOM_KUBERNETES_WORKER_CONFIG_* settings are removed.
Background scripts still running on Kubernetes workers during the upgrade are interrupted once when the primary starts.
Kubernetes workers pick up the new pod template when they are next recreated.
Plugin directories beside a file-sourced config are not visible to the sidecar or Kubernetes workers, so install proxied plugins as Python packages in the runner image.
Requester-scoped worker keys
v2026.9.33 changed the key of every user and user_agent worker, and workers from earlier releases are not reused or migrated.
After upgrading from an earlier release, reprovision every existing user and user_agent worker.
OAuth connections made for those scopes by ordinary Matrix IDs such as @alice:example.org keep working; reconnect any other integration connected for those scopes.
Shared and unscoped workers are unaffected.