How do migrants choose migration agents

Step 1: Setup Migration Manager agents

  • 4 minutes to read

When migrating file shares with Migration Manager, you first set up one or more "migration agents" by running a setup file on each computer or VM that you want to configure. When migration file shares with Migration Manager, you first set up one or more "migration agents", by running a setup file on each computer or VM you choose to configure.

When you run the setup file, you are prompted for two sets of credentials. You will need a SharePoint administrator credential to access your target and Windows credentials You need SharePoint Admin credentials to access your destination, and Windows credentials with read access to the source. Those Windows credentials must have read access to all file shares you plan to migrate. These credentials establish a trust relationship with the migration manager. This pair of credentials creates a trust with Migration Manager. The migration manager now sees the computer in question as an available "agent" to which it automatically Migration Manager now sees it as an available "agent" to which it can automatically distribute migrations tasks.

After an agent is configured, anyone with the permission to go into the SharePoint admin center can create tasks The tasks will be automatically distributed to one of the configured agents.


Make sure to download the latest version of the agent setup file.

Planning checklist

CategoryCategoryGuidanceFill in with your details
Have the right credentials to useSharePoint admin for migration destination Windows account for source that has access to ALL network file shares you plan to migrate Confirm that you have SharePoint Admin credentials to access the "destination" of where you are migrating your content. Make sure that you have the Windows credentials that you plan to use to configure the agent to access all Verify that the Windows credentials you plan on using to configure the agent has access to Alles the network file shares you plan to migrate.
Virtual machines or computers to use:Determine how many VMs or computers you plan on using for your migration project. List the computers or VMs before you begin.
Verify prerequisitesMake sure your computer meets the requirements.
Check required endpointsVerify that you have the required endpoints configured.
Multi-geo tenantIf you have a multi-geo tenant, make sure to understand where the agent will be installed.
Pre-provision OneDrive accountsIf you are migrating to OneDrive accounts, make sure the accounts are pre-provisioned before you migrate. Pre-provisioning can be done using a script, Pre-provisioning can be done by using a script as described here: Pre-provision OneDrive for users in your organization.
Government CloudGovernment CloudIf your tenant resides in a government cloud, you may have extra steps to perform before using Migration Manager.


Create a Windows admin account specifically to use for your migration project. Make sure this administrator account has access to any file shares that you want to migrate. Make sure this admin account has access to any file share that you plan on migrating. Log into each VM or computer with this account before you run the setup file.


Third party multi-factor authentication is not supported at this time.

Set up an agent

  1. Go to Migration in the new SharePoint admin center. You need to sign in with an account that has admin permissions for your organization.
  2. Under "For file shares" select First steps Under "For file shares", select Get started.
  3. Select the tab Agents and then Add.Select the Agents tab, and then select Add.
  4. Choose Download the agent setup file Select Download agent setup file.
  5. Open the setup file Click on the welcome page Further. On the Welcome page, select Next.
  6. Enter the SharePoint admin username and password of the environment where you will be migrating your content. Select Further Select Next.
  7. Enter the Windows credentials that will allow access to all Enter your Windows credentials that will provide access to Alles the file shares that contain the content you want to migrate To install Select Install.
  8. Test agent access (optional) or choose Shut down Test agent access (optional) or select CloseAfter the setup is completed, the new agent will be added to the available agents that can be assigned tasks.


Multiple agents.Multiple agents. If you have a large migration project and to set up multiple agents, we recommend that you download the agent setup file to a shared location. That way you can easily download the setup file on each computer or VM.

Working folder

A working folder named % appdata% \ Microsoft \ SPMigration is created for each agent. A working folder named % appdata% \ Microsoft \ SPMigration is created for each agent. This folder is where logs, reports, and any temporary folders are saved. Make sure your working folder has at least 150 GB of free space. Make sure that your working folder has a minimum of 150 GB of free space. It may need more depending on the size of the data you plan to migrate.

Multi-geo agent setup

If you have a Multi-Geo SharePoint tenant, the agent will be installed in the geo-location set in the SharePoint admin center. Before installing the agent, make sure the desired geo-location is the one set in the admin center To change an agent's geo-location, delete and reinstall the agent.

For more information, see Multi-Geo Capabilities in OneDrive and SharePoint Online.Learn more: Multi-Geo Capabilities in OneDrive and SharePoint Online

To install an agent to a different Geo location:

  1. Download the agent setup file.Download the agent setup file.

  2. Start the setup file and stay on the Home page.Launch the setup file and remain on the Welcome page.

  3. to open The file "% temp% \ SPMigrationAgentSetup \ SPMigrationAgentSetup \ Microsoft.SharePoint.Migration.ClientShared.dll.config".Open this file:% temp% \ SPMigrationAgentSetup \ SPMigrationAgentSetup \ Microsoft.SharePoint.Migration.ClientShared.dll.config

  4. Add an entry under "appSettings" as shown below example Under appSettings, add an entry as shown in the following example for the desired country or data center. (Note: this is an example for Canada.)

    < add key="GeoLocation" value="CAN" / >< add key="GeoLocation" value="CAN" / >

The country or regional GEO code can be found here Microsoft 365 Multi-Geo availability


Passwords are not stored in the installer.


Migration Manager automatically assigns tasks to a available agent.You cannot manually assign a task to a specific agent.Each agent can have up to 10 tasks in its Each agent can have up to 10 tasks in its queue.

Pausing a task does not release the agent to another task. An agent is still unavailable to take on a new task until the task continues and completes or until An agent remains unavailable to accept a new task until the task is resumed and completed, or if the task is deleted.


The connection between the agent and Migration Manager stays active as long as the computer is still running and the SharePoint admin credentials that were used to sign into the agent are still valid.

If the agent does becomes disconnected, it still holds the token to the Migration Manager for up to 7 days. After this period, the agent must be restarted After that time, the agent will need to be reinstalled.