shft

Frequently asked questions

Can users migrate between different macOS versions?

Yes. shft supports migration between any two Macs running macOS 14 Sonoma or later. The source and destination can be on different macOS versions (e.g., 14.3 → 15.1). shft does not depend on OS-level migration APIs, so version differences do not affect compatibility.

What happens if the connection drops mid-migration?

shft maintains a resume checkpoint on the destination Mac at ~/Library/Application Support/shft/transfers/<transferID>.json. This checkpoint records which files have been fully received and the last acknowledged chunk of any in-progress file.

When the connection drops:

  1. The transfer pauses and the UI shows "Connection Lost"
  2. The user reconnects the two Macs (replug the cable, rejoin the network)
  3. shft automatically resumes from the last checkpoint — completed files are not re-transferred
  4. Only the interrupted file restarts from the last successful chunk (1 MB granularity)

No data is lost on a connection drop. The worst case is that the last partial chunk (up to 1 MB) is re-sent.

Can an admin see what files were transferred?

No. Migration logs include category names, total sizes, and file counts, but they never include individual file names, file paths, or file contents. This is by design — see Logging: privacy considerations.

If you need file-level auditing, this is not a feature shft provides. The logs answer "did a migration happen, what categories were included, and did it succeed" — not "which specific files moved."

Does shft require internet access?

No. shft operates entirely over a local connection between two Macs. No data ever leaves the local network.

The only feature that uses internet is shft.logMigrationsToEndpoint — if configured, shft POSTs a JSON log to the specified URL after migration completes. If the endpoint is unreachable, the log is saved locally and the migration is unaffected.

Additionally, shft.brandingLogoURL loads an image from the specified URL at launch. If the URL is unreachable, the default shft logo is shown instead.

Can shft run alongside Migration Assistant?

No. Do not run shft and Apple's Migration Assistant at the same time on the same Mac. Both tools access similar file paths and system resources. Running them simultaneously can result in file conflicts, incomplete transfers, or data corruption.

Use one or the other. shft is designed as a replacement for Migration Assistant in enterprise environments, not a complement to it.

What if the destination Mac already has data on it?

shft handles this gracefully:

  • User Files: Files are written to the same relative paths. If a file already exists at the destination path, it is overwritten. If you need to preserve existing files on the destination, do not select the category that would overwrite them.
  • Application Data: Preferences and support files are written to their standard locations. Existing preferences are overwritten with the source Mac's values.
  • Keychain: Items that already exist on the destination are updated (not duplicated). New items are added.
  • System Settings: Preference domains are imported, overwriting any existing values for those domains.
  • Browser Data: Browser profiles are overwritten. If the user has set up new bookmarks on the destination, those will be lost.

Recommendation for device refreshes: Run shft on a freshly set up Mac (after MDM enrolment and app deployment, but before the user has customised anything). This avoids all overwrite conflicts.

Is keychain migration safe?

Yes, with caveats.

How it's secured:

  • Keychain items are exported using the macOS Security framework
  • The export is encrypted with AES-256-GCM using a session key derived from the pairing handshake
  • The encrypted data is transferred over TLS
  • On the destination, items are imported and the encrypted intermediate file is deleted
  • Keychain data is never written to disk unencrypted

What to consider:

  • Keychain migration copies all generic and internet passwords from the user's login keychain
  • This includes WiFi passwords, app-specific passwords, and any credentials stored by apps
  • iCloud Keychain items are excluded (they sync via iCloud automatically)
  • If your organisation uses a password manager and SSO, users may not need keychain migration — consider disabling this category

shft shows an explicit warning to users before they can enable keychain migration. The warning explains what will be copied and asks the user to confirm.

Can we restrict migration to business hours only?

Yes. Set shft.migrationWindowStart and shft.migrationWindowEnd in the configuration profile. For example:

<key>shft.migrationWindowStart</key>
<string>08:00</string>
<key>shft.migrationWindowEnd</key>
<string>18:00</string>

When a migration window is set:

  • Outside the window, the "Get Started" button is disabled
  • The welcome screen shows when the next window opens
  • Migrations already in progress are not interrupted when the window closes — only new migrations are blocked
  • Windows that span midnight work correctly (e.g., start 22:00, end 06:00)

What happens if the user exceeds the maxTransferSizeMB limit?

The limit is enforced before the transfer starts, not during. When the user reaches the manifest screen ("What to Move"):

  • Each category shows its estimated size
  • The total of all selected categories is displayed
  • If the total exceeds maxTransferSizeMB, the "Begin Transfer" button is disabled
  • A warning message tells the user: "Exceeds [limit] limit"
  • The user must deselect categories or folders until the total is within the limit

The user cannot start a transfer that exceeds the configured limit. If no limit is set (key omitted or set to 0), there is no restriction.

Does shft work with FileVault enabled?

Yes. FileVault encrypts the entire disk at rest, but when a user is logged in, the disk is unlocked and all files are accessible to applications running as that user. shft runs as the logged-in user and reads files through standard macOS APIs, so FileVault has no impact on functionality or performance.

Both the source and destination Mac can have FileVault enabled.

What if apps on the source aren't installed on the destination?

When the Application Data & Preferences category is selected, shft checks which apps are installed on the destination Mac before transferring. Application data for apps that don't exist on the destination is skipped.

The skipped apps are listed in the completion summary so the user knows which data didn't transfer. This prevents orphaned preference files from cluttering the destination.

Recommendation: Deploy apps via MDM to the destination Mac before running shft. This ensures app data transfers successfully because the matching app is already present.

Can two migrations run simultaneously on the same Mac?

No. shft supports one active migration per Mac. A Mac can be either a source or a destination in a single migration session. If you try to open a second instance of shft, it will recognise the existing session and refuse to start a new one.

What happens if the source Mac goes to sleep during migration?

The connection will drop and the migration will pause. When the Mac wakes up and the connection is re-established, shft resumes from the last checkpoint.

To prevent this, disable sleep on both Macs during migration:

  • System Settings → Displays → Advanced → Prevent automatic sleeping when the display is off
  • Or use caffeinate in Terminal: caffeinate -d -i -s (prevents display sleep, idle sleep, and system sleep)

Does shft transfer application binaries?

No. shft transfers application data and preferences — not the apps themselves. Apps should be deployed to the destination Mac via MDM before running shft.

This is intentional. In an enterprise environment, apps should come from a managed source (MDM, Self Service, VPP) rather than being copied from another Mac. This ensures the destination gets the correct, licensed, managed version of each app.