Migrating Windows devices with the agent

A provisioning package (PPKG) handles both Entra ID join and Intune enrollment in a single silent install. Generate one from the destination tenant before installing the agent.

• In the destination tenant's Intune portal, go to Devices → Enrollment → Windows → Bulk Enrollment Tokens.
• Click Create → follow the wizard to create a bulk enrollment token.
• Download the resulting .ppkg file.
• Upload the .ppkg to an accessible URL (Azure Blob Storage, SharePoint, or any HTTPS host). The agent downloads it at enrollment time.
• Copy the download URL — you will paste it into the FULL_MIGRATION command payload.

Download MigratorAgent.exe from Settings → Devices in your TheMigrator dashboard and run it on the target device from an elevated (Administrator) command prompt.

• Your orgId is shown on the Settings → Devices page.
• Run: MigratorAgent.exe /install /org <orgId> /api https://api.themigrator.app
• The installer registers the device, creates a Windows service (MigratorAgent), and sets it to start automatically.
• The device should appear in Settings → Devices within 30 seconds.

In TheMigrator → Settings → Devices, confirm the new device shows status ONLINE. The agent checks in every 3 minutes — if the device stays OFFLINE for more than 10 minutes, check that the service is running (services.msc → MigratorAgent) and that the device has internet access.

From the dashboard, select the device → Send command → FULL_MIGRATION. Paste the PPKG URL into the ppkgUrl field. Optionally fill in destTenantId for logging.

• Via the dashboard: Settings → Devices → [device] → Send command → FULL_MIGRATION → paste ppkgUrl.
• Via the API: POST /v1/devices/<id>/commands with body { "type": "FULL_MIGRATION", "payload": { "ppkgUrl": "<url>" } }
• The command status shows PENDING until the agent picks it up on its next check-in (within 3 minutes).
• The user on the device will see a 30-second shutdown warning — ensure they save any open work before sending the command.

Once the agent picks up the command it runs Phase 1 automatically. You do not need to do anything on the device during this phase.

• Step 1: Clears Outlook, Teams, and OneDrive credential caches while credentials are still valid.
• Step 2: Leaves the Windows domain (if joined) using netdom remove.
• Step 3: Runs dsregcmd /leave to leave the Azure AD / Intune enrollment (if enrolled).
• Step 4: Removes stale AAD certificates and CDJ registry keys.
• Step 5: Saves Phase 2 config (ppkgUrl, commandId) to the Windows registry.
• Step 6: Schedules a reboot in 30 seconds and reports RUNNING status to the API.

Phase 2 runs automatically when the MigratorAgent service starts after the reboot. No action is required.

• The agent detects the pending Phase 2 config in the registry on startup.
• Waits up to 5 minutes for network connectivity (login.microsoftonline.com).
• Downloads the PPKG from the ppkgUrl and runs provisioningcommandline.exe /install /quiet.
• Reports DONE (or ERROR) status to the API.
• Clears the Phase 2 registry key — if the device reboots again, Phase 2 will not re-run.

After Phase 2 completes, confirm the device appears in the destination Intune portal.

• In destination Intune → Devices → All devices, search for the hostname.
• Confirm Entra join status shows Azure AD Joined or Hybrid Azure AD Joined as expected.
• Confirm Compliance shows Compliant or In Grace Period (policies are applied over the next 15–30 minutes).
• Back in TheMigrator → Settings → Devices, the command should show status DONE with the result message.

If Phase 2 reports ERROR, check the result message in the command history. Common causes and fixes are listed below.

• PPKG install failed (exit code non-zero): verify the .ppkg URL is accessible from the device and the PPKG was generated from the correct Intune tenant. Re-generate and re-upload if the token has expired.
• Network timeout: the device lost connectivity after the reboot. Ensure the device has internet access before sending the command again.
• provisioningcommandline.exe not found: the device may be running a version of Windows that does not include the provisioning command line. Use the enrollmentUrl payload field as a fallback.
• To retry Phase 2 after a failure: send a new FULL_MIGRATION command or (if Phase 1 succeeded) an INTUNE_MIGRATION command — the device is already in a clean (no-tenant) state after Phase 1.