Switch an agent's runtime

You can move an agent to another runtime without recreating it. It stays the same agent, so its identity, memory, and chat history carry over. Before you confirm, Alfe shows a preview of exactly what’s kept and lost for that agent.

Before you start

Alfe refuses a switch in these situations, and the preview tells you why:

A managed agent is stopped. Start it first, because the switch rebuilds its machine.
The agent is mid-transition, or a machine upgrade or CLI update is in progress.
Your account has an unresolved billing issue.
The agent’s CLI is too old. Update it first, as described in doctor & upgrade.
The target runtime can’t run any model your organization has approved.

You also need permission to manage the agent.

Open the agent’s Settings tab, find Runtime, and select Switch runtime.
Choose the target runtime and review the preview.
Select Continue, then confirm the switch.
On a self-hosted agent, run alfe setup on the agent’s machine. This installs the new runtime, moves the workspace, and restarts the daemon.

Run this on the machine the agent runs on:

alfe runtime switch claude-code

The argument is a runtime ID: openclaw, claude-code, codex, gemini-cli, or grok-build. Pass -y or --yes to skip the prompt. Without a terminal, --yes is required.

On a self-hosted agent, the command then runs alfe setup for you. On a managed agent, it requests the switch and you follow progress in the dashboard.

What carries over

These stay with the agent on every switch:

Memory
Chat history
Connections
Secrets
Integration settings

Persona and workspace files also carry over, except in the cases below.

What you lose

The preview lists these for your agent:

In-progress runtime sessions. Open conversations start a fresh runtime session.
OpenClaw scheduled jobs and heartbeat settings, when you switch away from OpenClaw.
Your stored provider credential, when you switch away from a terminal runtime. Alfe deletes it, and model usage moves to Alfe credits.
Integrations the new runtime doesn’t support. They stop working until you switch back, and the preview names them.

If the new runtime can’t run the agent’s current model, the preview also shows the model it’ll change to.

What happens to files

The workspace depends on how the agent is hosted:

Managed, online. Alfe saves the workspace and restores it on the rebuilt machine. Files outside the workspace are lost, along with symbolic links inside it.
Managed, offline. The workspace can’t be saved, so every file on the machine is lost. You must accept that in the dashboard. The CLI refuses this case.
Self-hosted. alfe setup copies the workspace into the new runtime when the new one is empty. Your original files stay in place if it can’t.
To or from Hermes. Hermes keeps its workspace with its own install, so the workspace isn’t moved. On a self-hosted agent, the files stay on the machine.