Quick start

This walkthrough assumes xcross is already installed and on your PATH. See Installation if it isn’t yet.

# 1. One-time machine setup
xcross setup
xcross sdk install ~/Downloads/Xcode.xip
xcross auth --apple-id you@example.com

# 2. Once per device reconnect: mount DDI + start the RSD tunnel
#    (Administrator PowerShell on Windows; root on Linux)
xcross tunnel

# 3. Run on the device with hot reload
cd my_flutter_app
xcross flutter run

# 4. Optional: wire up your IDE
xcross ide vscode      # or: xcross ide idea

1. One-time machine setup#

Run these once per machine, in order:

• xcross setup installs host dependencies (apt packages on Linux, or checks Flutter/Swift/LLVM on Windows) plus pymobiledevice3.
• xcross sdk install ~/Downloads/Xcode.xip extracts the Darwin Swift SDK from a downloaded Xcode archive. See Darwin SDK.
• xcross auth --apple-id you@example.com signs in and saves a Developer Services session. See Authentication.

2. Connect the device#

xcross tunnel

Run this once per device reconnect, before xcross flutter run. It mounts the Developer Disk Image and starts the iOS 17+ RSD tunnel. Creating the tunnel interface needs elevated privileges: an Administrator PowerShell on Windows, or root on Linux.

3. Run on the device#

cd my_flutter_app
xcross flutter run

This prepares your app, launches it on the connected iPhone and keeps the process attached for hot reload. While it’s running:

Key	Action
r	Hot reload
R	Hot restart
q / Ctrl-C / Ctrl-D	Quit

With multiple iPhones connected, an interactive terminal shows a numbered device picker. For CI or piped runs where there is no interactive terminal, select the device explicitly:

xcross flutter run -u <UDID>

4. Optional: wire up your IDE#

xcross ide vscode

Sets up VS Code’s Run & Debug panel, Hot Reload/Restart buttons, and DevTools for this project. Use xcross ide idea instead for JetBrains IDEs via DAP. See IDE integration.

Next steps#

• CLI reference - device selection, flavors, dart-defines and every other flag
• IDE integration - full VS Code and JetBrains setup
• Troubleshooting - what to do if a step above fails