Moving a team to a new version¶
Export the old instance's setup, then import it into a fresh instance of the
new version. The simplest way needs no host commands: an owner types
/upgrade in a chat and the launcher writes the export
(Export from chat with /upgrade); then
onboarding's Import a team export choice opens it in the new data folder,
you choose what to bring, and the team starts
(Import during onboarding). Host commands do the
same and can also bring more records from the same backup later
(Export and review). Neither changes the signed export.
What moves¶
- Settings you changed in
instance_config.yaml, editable individually in YAML. Unchanged settings use the new release's defaults. - Control files:
SOUL.md, chosen model overrides, the roster, templates, agent definitions, specialist bundles, and Objective profiles. - Skills and tools: reviewed skills, added web API and CLI tools with their programs, MCP connections, and installed procedures.
- People and access: roles, channel bindings, Web Chat sign-ins, lasting grants, blocks (not TeamLead's restrictions for one request, which end with their request), shares, data folders, account links, person settings, and the team's choices of which services' accounts and model keys are shared (Shared or private). Disabled people stay disabled. Removed people do not move.
- Schedules and work setup: timing, instructions, enabled state, delivery routes, heartbeats, worker policies, pool limits, objectives and their policies. Each schedule has editable Markdown containing fenced YAML.
- Chat sessions: the sessions schedules deliver through and each person's current session in each chat, with their names but not their conversations. After the move, a person's next message continues in the session that was current in the old instance, even when an older session of the same chat moves too.
- Pinned memories, selected and editable one fact at a time.
- Knowledge pages: the team's pages and each imported person's own pages, with every revision, notes, links, the names of merged pages and pending contributions. Pages of people who are not imported stay behind. Selected notes, revisions, links and contributions that change a page need that page selected or already present. Contributions proposing a new page need no existing page. Later link selections must still appear in the destination page's current text; validation refuses links removed by destination edits.
- Credentials: operator secrets from
team.env, model keys, stored sign-ins, catalog entries, and password-manager sessions. The page shows names and owners, never secret values.
Agent-type grants and blocks keep their <team>/<type> IDs. Import checks the
type against this release's agents and the specialist definitions selected for
import. Unknown types, bare type names, and another team's subjects are refused.
The team lead's access for one person remains limited to that person's work.
Conversation and task history, the learned memory graph, workspace files, audit logs, queued tasks, and waiting approvals do not move. Automation jobs and managed services are listed for manual setup rather than imported. Missed one-time runs are imported turned off; recurring schedules resume counting from import.
Export from chat with /upgrade¶
An owner exports the whole team from a chat:
- Type
/upgradein a private chat with the assistant: Web Chat, or a direct message in Telegram, Discord, Signal, iMessage (Photon) or WhatsApp. The reply holds a link to a private page, and anyone who sees the link can open the page, so/upgradein a group chat is refused and asks you to send it in a direct message. Only owners can export the team; administrators who are not owners are refused. - Open the page and choose a passphrase. Type it twice, at least 12 characters and at most 1,024. It goes to the secure broker, is never sent to the agent and is not saved anywhere. Keep it: you need it to import the file. The page lists what the file holds.
- Wait for the export. The launcher writes one file into the data folder's
exports/folder, for example~/.universal-agents/data/exports/alpha-20261014-101500Z.uatransfer. This usually takes under a minute. The page and the chat then show the file's name and size, what it holds and the next steps. - Stop this instance, then import. Its chat bot tokens and model sign-ins move with the file, and two running instances must not use them at once. Continue with Import during onboarding.
What the passphrase protects. The stored sign-ins and keys and the
secrets from team.env are encrypted with the passphrase, and the whole file
is signed with it, so any change to the file is detected. The rest of the
team's records in the file (people, access, knowledge pages, pinned memories,
schedules, settings and team files) are not encrypted: anyone who has the file
can read them. Keep the file private, as you would a backup.
The file can be read only by its owner (mode 0600). The container runs as
root, so the launcher gives the file and exports/ to whoever owns the data
folder on the host; you can copy it without sudo. If that fails (for
example on some network folders), the export still succeeds and the page and
the chat say that copying the file may need sudo. Old exports stay in
exports/ until you delete them.
/upgrade needs the launcher (the Docker image, or docker/launch_headless.py),
because only the launcher holds every secret the export carries. A team
started another way is told to use team export on the host
(Export and review).
When the export does not finish, the page and the chat say why; run
/upgrade again. A half-written file is removed, even when the export process
is killed; if it was killed after it received the passphrase, the page says
the outcome is not known, so check exports/. The page stays open for one hour. Exports run one at a time: a
passphrase no export has picked up after five minutes is dropped (for example
because another export was still running), and the page says so. If the
secure broker restarts, the page link opens a page that can no longer start or
follow an export; run /upgrade again. An export that was already running may
still finish, so check exports/.
Import during onboarding¶
- Export the old team. Use
/upgrade(Export from chat with /upgrade) or runteam exporton the old instance as shown in Export and review, then stop the old instance. - Start the new version with an empty data folder. Onboarding opens, as for
a new team. Import works only on a fresh data folder and, for PostgreSQL, an
empty database named by
POSTGRES_DSNin the container's environment. - Copy the export into the new data folder's
import/folder, for example/srv/new-team/import/team.uatransferwhen/srv/new-teamis mounted as/data. Export files can be large, so there is no browser upload. - On Let's Begin, choose Import a team export. Choose the file, type its passphrase and select Open export. A wrong passphrase is refused; try again.
- Choose what to import. Records are grouped by kind and shown by name: people, schedules, memories, knowledge pages and so on. Everything starts selected; unselect what you don't want. Settings, memories and schedules can be edited as in the host-command review below. Open each selected schedule, check it, and confirm it.
- Choose where secrets come from. It starts with the old instance's choice. Turn on Secrets come from the environment when every secret reaches the container as an environment variable or Docker secret, as in Docker Swarm.
- Validate, then select Import and start the team. Onboarding writes the instance and the container starts the team. The page opens Web Chat when it is ready.
The copied export and the review's private files are deleted after the import;
the original stays where you exported it. Stored sign-ins and keys are imported
by the new instance's broker when the team first starts. Each person whose
sign-ins moved gets an Inbox notice, and the owner who exported the team gets
one listing any the broker did not store. Until then they wait, still encrypted,
in a private file under state/; the passphrase is never saved. The broker
restores them before agents and Web Chat start. Temporary storage failures are
retried during startup. If the broker cannot be reached or those failures
persist, startup stops and keeps the encrypted handover for the next start;
python -m assistant_cli team finish-import --config /data/instance_config.yaml
runs the same step by hand.
An import is marked complete only after this handover has been saved. If its write fails, the instance stays unfinished and cannot start. Use a fresh data folder and empty databases to repeat that first import. A failure opening an export leaves completed review edits intact and can be retried.
When secrets come from the environment, the import lists the secrets the
environment is missing, including those the old team.env held. Add them as
Docker secrets and restart the container; the team then starts.
Export and review¶
Choose a passphrase of at least 12 characters and an active owner's person id
(/user list shows ids). Keep the passphrase and export private. Run these
operator commands with the release that owns each instance; agents cannot run
them.
.venv/bin/python -m assistant_cli team export \
--config <old-root>/instance_config.yaml --owner <owner-person-id> \
--out team.uatransfer
The command prompts for the passphrase twice. --passphrase-file <file> reads
it from a private file instead; the passphrase is never a command-line value.
--skip-credentials omits broker credentials if the old broker cannot run.
Stop the old instance immediately after export: bot tokens and rotating sign-ins
must not serve two running instances.
The first import needs a fresh root without existing configuration, control
files, or databases. For PostgreSQL, create empty destination databases and set
POSTGRES_DSN or POSTGRES_DSN_FILE in the destination environment or planned
team.env. --env <file> loads a destination environment file. All import
writers and the next launch resolve those settings the same way. The first import
checks each effective destination database, including the bundled PostgreSQL
server and a separate activity database, and refuses any that already hold
tables. Pick database locations
and the secret source in the first batch; later batches cannot move existing
data or keys to another location.
Open the browser review using the new release:
.venv/bin/python -m assistant_cli team review \
--in team.uatransfer --instance-root <new-root> --review-dir <private-review-folder>
The command opens a private loopback page and prints its URL. Keep the command running while reviewing; Ctrl+C closes it. Run it on the destination host. For a remote host, forward the printed port through SSH and open the same loopback URL locally, preserving its token fragment. This is an operator page, separate from the gateway.
- Filter and select individual records. Include at least one active owner in the first batch. Dependencies must be selected or already present, such as a schedule's person, chat session, objective, delivery target, worker binding, and worker definition.
- Open each selected schedule. Check timing, timezone, instructions, enabled
state, owner, and delivery route. Edit and save its Markdown. The one fenced
YAML block is the imported configuration; surrounding prose is review notes.
IDs, ownership, routes, and approval provenance cannot be changed this way.
Leave a wrong-owner or wrong-route schedule unselected and recreate it using
the normal schedule controls.
The page shows the backup's remaining run count. Keep
repeat_countunchanged to preserve that progress; changing it sets the number of runs remaining after import (nullmeans unlimited). Worker setup must match the selected worker type. Edited worker instructions may need the normal worker review after startup. - Confirm each selected schedule after its final edit. Editing again clears confirmation. Settings and memories are editable too, in the page or with your own text editor.
- Choose Validate selected records. Review attention notes; correct or unselect refused records. Validation reads destination stores without initializing or repairing them. Blank memories and schedules that cannot produce a next run are refused before anything is written. Invalid YAML reports its line and column so you can correct the saved edit and retry.
- Choose Import selected records. The server checks the exact saved review you validated. Noncredential batches require a stopped destination runtime. Pending saves and unsaved edits keep import disabled. If you edit during validation, save the current text and validate again.
The private review folder contains review.json, schedule Markdown in
schedules/, setting YAML in settings/, and memory text in memories/. It is
bound to this exact signed backup and destination root. It can contain private
instructions and memories, but no decrypted broker credentials.
Credentials and later batches¶
Start the new instance after the first noncredential batch. Stored credentials go through the running broker. Reopen the page, select a credential batch, then validate and import. Unselect pending noncredential records for a broker-only batch while the runtime runs. If credentials were attempted before the broker started, the page reports that they were not stored; start it and retry them. Each person whose credentials move receives an Inbox notice.
Keep the original backup and review folder until all wanted records have moved.
Reopen team review with the same arguments to select more records. Later
batches require the exact backup used for the first batch. Already imported
records are skipped, preserving destination edits. Existing records with the
same identity, including credentials stored after startup, are kept too.
A chat that already continues in a session in the new instance stays in it.
If a later batch brings the session that was that chat's current one in the
old instance, the session is imported and marked for attention, and people's
next messages still go to the session they use now.
Distinct credential and field names keep separate secret values, including
names that differ only in punctuation. Importing a catalog credential does
not overwrite a secret used by another existing catalog entry.
If storing a catalog credential fails, retry the same backup. The broker reuses
that record's stored secret items and saves its complete catalog entry together,
so a partial attempt does not block the retry or create duplicate secret items.
Account links belong to their owner and tool, so an older link cannot replace a
newer destination sign-in even when their link IDs differ. An access decision
whose result is still being confirmed must be reconciled before export. Start
the gateway and let the Inbox check it after the ten-minute claim period,
then stop the runtime and export again. Each tool has one
link per owner; if a backup holds two for the same tool and owner, the review
refuses the older one and names the newer one, which was the one in use. A person's chat
account already linked to someone in the destination is refused before writing,
including accounts retained after that person leaves the team.
Stop the destination before adding more settings, people, schedules, or memories.
Back up its root and databases before each later batch. Receipts and reports
are stored in runtime/team-import/. A failed noncredential import leaves a
marker that blocks every runtime entry point. For a failed first import, use a
fresh root and empty databases. For a failed later batch, restore the pre-batch
root and database backups before retrying. Removing the marker does not repair
partially written records.
CLI and Docker¶
The CLI also applies saved reviews. Writing imports now require --review;
an unreviewed --dry-run remains available.
.venv/bin/python -m assistant_cli team import --in team.uatransfer \
--instance-root <new-root> --review <private-review-folder> --dry-run
.venv/bin/python -m assistant_cli team import --in team.uatransfer \
--instance-root <new-root> --review <private-review-folder>
.venv/bin/python -m assistant_cli team import-credentials --in team.uatransfer \
--config <new-root>/instance_config.yaml --review <private-review-folder>
team inspect --in team.uatransfer verifies the archive and lists its sections.
Delete private transfer and review files when the move is complete.
With Docker, export and import credentials inside the matching running container:
docker exec -it <old-container> python -m assistant_cli team export \
--config /data/instance_config.yaml --owner <owner-person-id> --out /data/team.uatransfer
docker exec -it <new-container> python -m assistant_cli team import-credentials \
--in /data/team.uatransfer --config /data/instance_config.yaml --review /review
For browser review on Linux, use a disposable container with host networking. Mount the destination and review folders at the same absolute paths used by the normal instance, because those paths are saved. For example:
docker run --rm -it --network host --entrypoint python \
-v /srv/new-team:/srv/new-team -v /srv/team-review:/srv/team-review \
<new-image> -m assistant_cli team review --in /srv/new-team/team.uatransfer \
--instance-root /srv/new-team --review-dir /srv/team-review/review
The example's review subfolder must initially be absent. Docker Desktop does not expose container loopback this way; use the new release's host installation to review with access to the same destination files.
Which versions can read a file¶
Each section has its own version. A release reads its own section versions and the ones the release just before it exported, converting the sections that changed. No release reads an older database directly.
A file from an older release is refused before anything is written. The message names the release that exported the file. Import it into a newer release that can read it and export the team again there. Repeat with newer releases until this release can read the file. Use the release paths below; one intermediate export may still be too old for this release.
This release reads files exported by v0.9.1 and v0.9.2. Files exported by v0.8.5 or v0.9.0 are read by v0.9.2: import such a file into v0.9.2, export the team again there, and import that file here. Later batches from the older file also need v0.9.2, so finish them before you upgrade.
Files exported by v0.8.1, v0.8.2 or v0.8.3 are read only by v0.8.4: those releases export the same section versions.
These files have no credential index. After the first noncredential import
into v0.8.4, start its broker, then open team review with a new
--review-dir folder. Select and import the stored credentials before
exporting again. Reopening the first review folder does not discover them.
Files exported by v0.8.4, the last release before shared and private
accounts, are read only by v0.8.5. Import such a file into v0.8.5, export the
team again there, and continue with that file through v0.9.2 as above. Later
batches from a v0.8.4 file also need v0.8.5, so finish them before you upgrade. v0.8.5 keeps how the old team
treated people added later (they use the team's model keys only if
gateway.users.new_people_use_team_model_keys was on), and its export carries
that choice as the team's model-key sharing.
v0.8.4 and v0.8.5 refuse agent-type grants and blocks. Unselect refused records in review, then recreate them with that release's access commands before starting each intermediate instance. Enabled imported schedules can otherwise run without their original blocks. The steps below describe how to restore and check that access.
When a release renames tool operations, review and import convert the blocks that name them. Backups made before the action tools were merged still need those renames. A block on one memory bank's old function covers that action for both banks. A block naming an operation this release does not have is listed for attention, including operations of accepted team-added CLIs, web APIs and active MCP servers. Review checks their imported definitions before writing the new instance. Such a block stops the whole tool until an administrator replaces it (see Blocking access).
Instances older than v0.8.1¶
v0.8.0 and earlier releases have no team export. Choose one of two ways.
Start fresh and keep pinned memories. Onboard a new instance of this
release on its own data folder. Enter model keys and chat bot tokens in
onboarding rather than uploading the old team.env, which would bring back
the old internal keys and turn model keys into overrides. Move pinned
memories with memory export and memory import
(Moving memories to a new instance).
People sign in to their accounts again with /link, and administrators link
the team's accounts with /link <tool> team. Settings, access, schedules and
added tools stay behind.
Move everything through v0.8.1. Each step needs the release named in it.
- Back up the instance root and its databases, then start the instance once
on v0.8.1. The Docker start converts
instance_config.yamlto the v0.8.1 format; check withpython -m assistant_cli migrate-config --config <root>/instance_config.yaml --yes, which also converts it when needed. The v0.8.1 export copies the file as saved, so an unconverted file brings old settings the next release refuses. - Save the output of
python -m assistant_cli access list --config <root>/instance_config.yaml. v0.8.4 and v0.8.5 refuse grants and blocks given to an agent type, such as the team lead's access for one person or a block on a worker type. Unselect them in each intermediate review. After the noncredential imports at each hop, recreate them with that release'saccess grantandaccess blockcommands and check them withaccess listbefore starting the instance. Preserve whose work each grant serves, its level, expiry and delegation settings, and each block's subject and target. Imported recurring schedules remain enabled; without their blocks, they can perform previously blocked actions as soon as the intermediate instance starts. - Export on v0.8.1 and stop the old instance.
- Import all wanted noncredential records into a fresh v0.8.4 instance and
restore the access recorded in step 2 before starting it. v0.8.3 renamed the
default assistant from Assistant to Lisa. To keep the old name, edit the
imported v0.8.4
instance_config.yamland setassistant.display_nametoAssistantbefore the next export. An unchanged old default is absent from the export, so the review has no setting for it. - Start the v0.8.4 instance. Open
team reviewwith the same backup and destination but a new--review-dirfolder to discover its stored credentials. Select only the credential batch, validate and import it. Finish all wanted batches, then export on v0.8.4 and stop that instance. - Import all wanted noncredential records from that file into a fresh v0.8.5 instance. Again, unselect refused agent-type grants and blocks in review and recreate them before startup. Start it, finish its credential import and all wanted batches, then export on v0.8.5 and stop it.
- Import the v0.8.5 file into a fresh v0.9.2 instance. Select the restored agent-type grants and blocks; v0.9.2 accepts them. Check the access list against the saved one before startup. Start it, finish its credential import and all wanted batches, then export on v0.9.2 and stop it.
- Import the v0.9.2 file into this release, check the access list again before startup, then finish the credential import as described above.
For moving only pinned memories, see Moving memories to a new instance.