Run your first migration with PowerSyncPro

PowerSyncPro doesn't run in isolation — your migration's success depends on the endpoint and identity infrastructure already in place around it. The platform's own prerequisites are covered in the install step; what follows is the wider environmental groundwork that decides whether migrations land cleanly. A non-exhaustive list of things to confirm before you start:

• Target environment readiness — the single biggest predictor of a smooth migration. Before running any PowerSyncPro migration, provision a fresh test device directly into your target environment using your standard process (Autopilot, manual Entra-join, AD join — whichever applies). Confirm it lands cleanly: enrolment or domain-join completes, policies behave correctly, applications deploy, and the user can sign in and be productive. If your target isn't ready for fresh devices, it won't be ready for migrated ones.
• Uninterrupted connectivity for migrating devices — during migration, the agent briefly puts the device into a workgroup-joined state and then reaches out to complete the target join. The device needs continuous access to both the target environment and your PowerSyncPro server throughout the entire migration window. Confirm Wi-Fi profiles, VPN configurations, and any always-on connectivity tooling will keep the device online — a dropped connection mid-migration can leave the device in a pending state, without reporting its progress.
• EDR / AV on the endpoint — confirm exclusions for the Migration Agent on every device that will migrate, in whichever endpoint protection product you run (Defender, CrowdStrike, SentinelOne, etc.). Aggressive policies can interfere with profile repermissioning during migration. EDR / antivirus symptoms and resolutions →
• Source EDR cleanup — if your migration involves replacing endpoint tooling between source and target (a common pattern in tenant-to-tenant moves), the Runbook's pre- and post-migration script hooks are designed for exactly that kind of cleanup. Run the source EDR's removal command pre-migration; install and register the target EDR post-migration.
• Policies — review GPOs (and the target's equivalents) that apply to migrating devices, particularly anything that would conflict between source and target.
• Management plane — if you're moving between management tools (SCCM, Intune, one Intune tenant to another), confirm that enrolment profiles and compliance policies are configured for the target. For SCCM source environments specifically, you may need to uninstall the SCCM client ahead of migration via a startup script — the SCCM client can interfere with management-plane transitions. Common Intune enrolment issues →
• Autopilot — if you rely on Autopilot, confirm deployment profiles and group assignments in the target, and plan the workflow for moving hardware-hash registrations if you're changing tenants.

These elements are outside the scope of PowerSyncPro and require domain-specific expertise. If you'd like hands-on help getting the environment ready, our PowerSyncPro partner network includes consultants experienced in running these projects end to end.

The platform runs on a single Windows server. Pick the path that fits your environment — each lands you with a working PowerSyncPro server, ready to configure. A single server can host migrations for multiple customer environments, which makes it well-suited to MSP and consulting deployments.

The PowerSyncPro server needs to be continuously reachable by the Migration Agents on each endpoint, and — if you're pulling in remote directories — by the Remote Sync Agents in those networks. Three things to configure: a DNS A-record, an SSL certificate, and the right inbound ports.

DNS. Set up an A-record pointing at the PowerSyncPro server (e.g. psp.company.com). Endpoints and agents will use this hostname when they register and check in.

Ports. The PowerSyncPro server is reached inbound by Migration Agents on endpoints and — if you're using them — by Remote Sync Agents in off-network directories. The table below covers the default ports involved:

TCP 5001 only applies if you're running a Remote Sync Agent, and should be restricted to the trusted networks where those agents live — never exposed to the public internet.

Migration Agent traffic (TCP 443) can be fronted by a reverse proxy (Azure App Proxy, Cloudflare, NGINX) or a WAF if your organisation requires it — PowerSyncPro doesn't care how the request reaches the server, as long as it does. Sync Agent traffic (TCP 5001) is different: it uses gRPC, which most reverse proxies and WAFs don't proxy cleanly. We recommend exposing 5001 directly to the trusted networks where Remote Sync Agents live, rather than putting it behind a proxy — unless your proxy explicitly supports gRPC.

Not sure which agents you'll need (and therefore which ports apply)? The Architecture Advisor takes a few inputs about your environment and returns the list of components — Sync, Password, Proxy — that fit your migration.

Tell PowerSyncPro about the directories it's going to read for source and target identity information. A migration always has at least two — a source and a target — and the connections you create here are how every later step finds them. You'll configure one connection for your source and one for your target; the options below apply to each side independently, since source and target may have different shapes (AD vs Entra) and different network postures.

What the directories give you, in practice:

• Devices — imported so PowerSyncPro can register agents (only devices your directory knows about can register) and so you can scope Batches by device. Typically from the source.
• Users — imported on both sides so the sync profile can match each source user to a target user. This builds the Translation Table that the Migration Agent uses to repermission profiles, files, and settings during migration.

If either side is in GCC High, the App Registration setup differs slightly from a commercial tenant — see the GCC High KB article for the exact path. Also linked at the bottom of this step.

Unsure which approach is right for your environment? The Architecture Advisor walks through the decision factors and points you at the best fit.

For directory reads in online migrations, a read-only service account is sufficient on both source and target — Match Only sync profiles don't write back, and the AD join itself is handled by a separate Runbook-level credential with computer-create rights (configured later in step 7, in Device State).

For Offline Domain Join, however, the directory connection's service account also performs the domain join itself — pre-creating the target computer account and generating the offline join blob. In ODJ scenarios, the target directory connection's service account needs computer-create rights in the target OU, not just read. This applies whether the directory connection uses direct line of sight or a Remote Sync Agent.

Tenant-to-tenant scenarios need two Entra connections (one per tenant). The migration guide for your scenario tells you exactly which connections you need and what permissions each requires.

This is where DirSync earns its keep — even if you only care about workstation migration. The sync profile creates the Translation Table: the mapping between each user's source identity and their corresponding target identity. Under the hood, this is a SID-to-SID translation that Migration Agent uses during migration to repermission profiles, files, and settings on the device, so the new account inherits all the existing access. No translation entry, no repermissioning — this step matters for nearly everyone.

For workstation migration you'll want a Match Only profile: read-only on both directories, with nothing created, modified, or deleted. It just builds the mapping. How you match is the decision below.

Pick an approach you can rely on for every user you plan to migrate. If a user can't be matched — values differ, attribute is missing, expression doesn't apply — they won't end up in the Translation Table, and they won't have their profile migrated when their device runs. The migration guide for your scenario calls out which strategies fit that path.

This is where you tell PowerSyncPro what a migration looks like and which devices are part of it. These are two separate concepts, and they're both worth understanding clearly because they're paired in every migration you run.

Two patterns are used to schedule migrations. A self-service migration with a deadline opens migration up to users early so they can start it themselves via the Migrate Now option in the PowerSyncPro Migration Agent tray icon — most migrate at their own pace, and Enforced After catches the rest. A Big Bang waits until administrators are ready, then fires migration for everyone in the Batch at a coordinated moment. The Available From and Enforced After dates can be set to reflect either pattern. Which one fits depends on how much coordination your project needs, and the migration guide for your scenario will recommend the right approach.

Everything up to this point — install, directories, sync profile, Runbooks, Batches — can be done without a licence. The licence is what lets you actually migrate a device. That includes testing: real migrations on test machines require a real licence, which is what trial licences are for.

What you need a licence for

• Migration Agent — required to migrate a device. Workstation migration projects only need this.
• DirSync — only required if you're using DirSync to export data to a target directory (creating, updating, or synchronising users). The match-only sync profile that powers the Translation Table for workstation migration doesn't need a DirSync licence.

What you'll need when you order

Licences are scoped to a specific device count and to your specific source and target domains. Have these ready:

• Your device count
• Your source domain — Active Directory FQDN (e.g. company.com) for AD, or onmicrosoft.com tenant domain for Entra
• Your target domain — same shape, for the target side

How to apply it

Your licence arrives as a single string. In the admin console, go to Global Settings → Licences, paste it in, and save.

Test in two phases, with a real expectation that you'll iterate between them.

If anything surprises you in either phase, fix it in the configuration and re-test. If something doesn't behave the way you expect and it's not obviously a config problem, open a support ticket — our team is well used to debugging this kind of edge case.

Now that you've proved the configuration works on representative hardware, push the Migration Agent to your endpoint fleet. The agent is a small Windows service that sits dormant on the device until a Runbook tells it to act, so deploying it ahead of time is safe. You already created the Migration Agent certificate and the pre-shared key for the test phase — they're reused as-is for the fleet rollout.

• Intune (Line-of-Business MSI app) — recommended — the simplest path for modern, cloud-managed fleets. Upload the MSI as a LoB app, supply the install command-line arguments below, and target device groups (not user groups).
• SCCM / MECM — well-suited to traditional or hybrid AD environments. Use the Application model so you get detection rules and reporting; deploy to a pilot collection first.
• PDQ / RMM / PowerShell — flexible automation for mixed fleets and MSP engagements. The MSI is silent-installable and can be wrapped in any deployment tool; the KB has a ready-made PowerShell template.
• Manual install — fine for small fleets, pilots, lab testing, or war-room migrations.
• Group Policy (GPO) — supported but with significant limitations: install runs only at system startup, requires DC contact before user logon, and has no built-in retry or detection. Configuration values can't be passed as command-line arguments, so a custom MST transform is required (the KB has a script to generate one). Use only when nothing else fits.

However you deploy, the MSI takes two parameters at install time: URL (your PowerSyncPro Agent registration endpoint, e.g. https://psp.company.com/Agent) and PSK (the pre-shared key you generated above). The agent uses these to register itself with the server. Verbose MSI logging is strongly recommended on every deployment method — see the KB for the exact arguments.

The MSI ships in two flavours — with and without .NET bundled. Use the self-contained one if you're not sure your endpoints have the right .NET version; use the slim one if you control your fleet and know they do.

When a device is in a Batch and inside its migration window, the agent picks up the Runbook and runs the migration. If a user is logged in, they see a small set of guided screens; if not, the agent runs the migration as SYSTEM in the background — no interactive session needed. Under the hood, PowerSyncPro changes the device's directory join state, repermissions the user's profile and files using the Translation Table, handles BitLocker and Windows Hello reset, and reconfigures applications as defined in the Runbook.

The migration completes across several reboots. User profiles, settings, and files are preserved — when the user logs back in with their target account, their desktop, documents, browser bookmarks, and installed apps are where they left them. Most users describe the experience as seamless; many don't realise the device has moved directories at all. After migration, the agent stays dormant on the device — useful if you ever need to run a follow-up Runbook on the same hardware.

Migration progress and per-device logs surface in the admin console under Agent Logs. PowerSyncPro also writes to the device's Application Event Log, which is the first place to look when troubleshooting on the machine itself.