Apus supports three migration paths: importing from another agent system, moving an existing install to a new machine, and upgrading a plugin in place.

Import from another agent system

Bundled migration providers bring instructions, MCP servers, skills, model config, and (opt-in) API keys into Apus. Plans are previewed before any change and secrets are redacted in reports. Standalone apus migrate is backed by a verified backup; fresh onboarding imports instead stage and verify local artifacts before publishing them with configuration committed before any irreversible external activation.

Import Claude Code and Claude Desktop state, including `CLAUDE.md`, MCP servers, skills, and project commands.

Import Hermes config, providers, MCP servers, memory, skills, and supported `.env` keys.

The CLI entry point is apus migrate. Onboarding can also offer migration when it detects a known source (apus onboard --flow import).

Move Apus to a new machine

Copy the state directory (~/.apus/ by default) and your workspace to preserve:

• Config — apus.json and all gateway settings.
• Auth — shared and per-agent SQLite auth stores (API keys plus OAuth), plus any channel or provider state under credentials/.
• Sessions — conversation history and agent state.
• Channel state — WhatsApp login, Telegram session, and similar.
• Workspace files — MEMORY.md, USER.md, skills, and prompts.

Migration steps

On the **old** machine, stop the Gateway, then create and verify a backup
archive:

```bash
apus gateway stop
mkdir -p ~/Backups/apus
apus backup create --output ~/Backups/apus --verify
```

Stop the Gateway before taking a machine-move snapshot. A raw copy of a
changing SQLite database can capture mismatched database and WAL files;
quiescing the Gateway also keeps the rest of the state tree stable. If you
use multiple profiles, run the command once with each profile selected.

[Install](/install) the CLI (and Node if needed) on the new machine. It is fine if onboarding creates a fresh `~/.apus/` — you overwrite it next.

Transfer the generated `.tar.gz` archive via `scp`, an external drive, or
another protected channel. On the new machine, restore it to a fresh
staging directory:

```bash
apus backup restore <archive.tar.gz> --target ~/apus-restored
```

Restore never activates in place. With the Gateway stopped, use the
restored `manifest.json` mapping to move the state and workspace assets to
their recorded destinations, or point `APUS_STATE_DIR` at the restored
state asset. Confirm ownership matches the user that will run the Gateway.

Absolute symbolic links keep their original target locations, including
links to separately backed-up config or credentials. Before activating
state on another machine or at another path, review these links and make
sure their targets are correct for the new location. See the
[backup symbolic-link caveat](/cli/backup#what-gets-backed-up).

Restoring older channel state can desynchronize ratcheting credentials such
as WhatsApp. Approvals and delivery/dedupe state also roll back, and plugin
`node_modules` trees must be reinstalled. See [Restore a full archive](/install/backups#restore-a-full-archive).

On the new machine, run [Doctor](/gateway/doctor) to apply config migrations and repair services:

```bash
apus doctor
apus gateway restart
apus status
```

If Telegram or Discord uses the default env fallback (TELEGRAM_BOT_TOKEN or DISCORD_BOT_TOKEN), verify the migrated state-dir .env contains those keys without printing the secret values:

awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.apus/.env

apus doctor also warns when an enabled default Telegram or Discord account has no configured token and the matching env variable is unavailable to the doctor process.

Common pitfalls

If the old gateway used `--profile` or `APUS_STATE_DIR` and the new one does not, channels will appear logged out and sessions will be empty. Launch the gateway with the **same** profile or state-dir you migrated, then rerun `apus doctor`.

The config file alone is not enough. Shared model auth lives in `state/apus.sqlite`, agent-local profiles live in `agents/<agentId>/agent/apus-agent.sqlite`, and channel and provider state lives under `credentials/`. Always migrate the **entire** state directory using the backup and restore flow above.

If you copied as root or switched users, the gateway may fail to read credentials. Ensure the state directory and workspace are owned by the user running the gateway.

If your UI points at a **remote** gateway, the remote host owns sessions and workspace. Migrate the gateway host itself, not your local laptop. See [FAQ](/help/faq#where-things-live-on-disk).

The state directory contains auth profiles, channel credentials, and other provider state. Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.

Verification checklist

On the new machine, confirm:

• [ ] apus status shows the gateway running.
• [ ] Channels are still connected (no re-pairing needed).
• [ ] The dashboard opens and shows existing sessions.
• [ ] Workspace files (memory, configs) are present.

Upgrade a plugin in place

In-place plugin upgrades preserve the same plugin id and config keys but may move on-disk state into the current layout. Plugin-specific upgrade guides live alongside their channels:

• Matrix migration: encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands.

Related

• apus migrate: CLI reference for cross-system imports.
• Install overview: all installation methods.
• Doctor: post-migration health check.
• Updating: updating an existing install in place, plus rollback strategy.
• Uninstall: removing Apus cleanly.
• apus backup — create the archive this migration restores