Skip to content
xcross
Documentation menu

Quick start

Go from an installed xcross binary to a running, hot-reloadable Flutter app on a physical iPhone.

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. Check build and run requirements without changing anything
cd my_flutter_app
xcross doctor

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

# 4. Run on the device with hot reload
xcross flutter run

# 5. 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. Check requirements

From your Flutter or Compose project, run:

xcross doctor

Doctor checks the Linux or Windows host tools, Darwin SDK, current project, authentication, device tooling, and connected iOS versions without building, installing, or launching anything. Missing project or device context is a warning; failed requirements return a nonzero exit code.

3. 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.

To run without a cable, use xcross tunnel --wifi instead. With USB attached it bootstraps wireless pairing through the cable; without USB it reconnects a saved device or, on iOS 27+, guides you through pairing under Settings > Privacy and Security > Developer Mode > Paired Devices. See Run over Wi-Fi.

4. 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:

KeyAction
rHot reload
RHot restart
q / Ctrl-C / Ctrl-DQuit

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>

5. 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

Edit on GitHubReport an issue
ESC