ioscpy

待办

• https://github.com/lautarovculic/ioscpy/issues/7
• 侧面板中的屏幕录制（显示状态）按钮。
• 研究：为 Windows 提供带 GUI 的支持，安装程序（预留，作者将完整实现）
• 添加认证与授权，并在设备上显示“ioscpy 正在运行”的通知（预留，作者将完整实现）
• 使 ioscpy 无线化（蓝牙、Wi-Fi）（预留，作者将完整实现）
• 自定义按钮操作（宏）（分阶段，概念将很快推出）

一款 macOS、Linux 和 Windows 的 CLI 工具，可通过 USB 镜像并控制越狱后的 iPhone。

只需连接一个设备即可。它会自动连接。

安装

涉及两侧。Mac 应用运行镜像，iPhone 软件包让手机可以被控制。请同时安装两者。

在 Mac 上，使用 Homebrew：

brew tap lautarovculic/ioscpy   # Mac 应用
brew trust lautarovculic/ioscpy
brew install ioscpy
ioscpy --version

在越狱后的 iPhone 上，在 Sileo 或 Zebra 中添加此源，然后安装 ioscpy 并注销：

https://lautarovculic.github.io/ioscpy-repo/

该源同时提供无根（rootless）和有根（rootful）构建版本，包管理器会自动选择与越狱匹配的版本。

ioscpy --device <UDID>   # 当连接多个设备时选择一个
ioscpy --list            # 列出已连接的设备
ioscpy --no-keyboard     # 隐藏屏幕键盘，从 Mac 输入
ioscpy --mjpeg           # 强制使用 MJPEG 视频而非默认的 H.264
ioscpy --debug           # 完整诊断
ioscpy --version

Linux

目前尚无 Linux 预编译版本。请从源码构建主机端。设备端的软件包与 macOS 相同，通过上述 Sileo/Zebra 源安装。

克隆此仓库，然后运行安装脚本：

./install.sh

--yes 跳过确认提示。--prefix DIR 安装到 DIR 而不是 /usr/local，并且当目录在 $HOME 下时省略 sudo。--uninstall 删除已安装的二进制文件。

手动安装

在 Debian/Ubuntu 上的前置条件：

sudo apt install build-essential pkg-config nasm \
                 libimobiledevice-utils usbmuxd \
                 libxkbcommon-dev libwayland-dev \
                 libxcb1-dev libxkbcommon-x11-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

确保 usbmuxd 正在运行，以便设备能够显示：

sudo systemctl enable --now usbmuxd
idevice_id -l   # 连接手机后应输出 UDID

以普通用户身份构建主机端，然后安装：

make host-release
sudo make install-host    # 安装到 /usr/local/bin/ioscpy
ioscpy --version

对于 Arch Linux

./install.sh 也适用于 Arch Linux。

sudo pacman -S --needed \
  base-devel pkgconf nasm \
  libimobiledevice usbmuxd \
  libxkbcommon wayland libxcb libxkbcommon-x11 \
  rustup curl git

rustup default stable

启用服务

sudo systemctl enable --now usbmuxd.service

检查设备是否已连接

idevice_id -l

然后运行二进制文件

cd host/target/release && chmod +x ioscpy

./ioscpy

构建步骤仍由普通用户执行，这样才能找到通过 rustup 安装的 cargo。install-host 是一个单独的目标，仅复制构建好的二进制文件，因此可以在 sudo 下正常运行，无需在 root 的 PATH 中设置 cargo。如需在用户目录下安装（无需 sudo），可使用 make install-host PREFIX=$HOME/.local，并确保 $HOME/.local/bin 在 PATH 中。

在 Linux 上，H.264 解码通过 openh264 软件解码器工作。如果希望使用 MJPEG 路径，请传递 --mjpeg。

对于拒绝服务器端装饰（GNOME/mutter）的 Wayland 合成器，ioscpy 会自动回退到 X11/XWayland，以便窗口获得正常的标题栏。如果希望停留在原生 Wayland 上，请传递 --wayland。

Windows

目前尚无 Windows 预编译版本。请从源码构建主机端。设备端软件包与 macOS 和 Linux 相同，通过 Sileo/Zebra 源安装。

Windows 上的 ioscpy 会复用 iOS 设备已有的 USB 工具，并且不会替换任何驱动程序，因此 Frida、objection、grapefruit、ideviceinfo、iTunes 以及其他 usbmux 工具在运行时依然能正常工作。

1. USB 栈

• Apple Mobile Device Support：随 iTunes 从 apple.com 安装（获取 Apple 官网版本，而非 Microsoft Store 版本），或者独立安装 AMDS 包。这将提供 USB 驱动程序和 usbmuxd。iTunes 必须能够看到手机。

• libimobiledevice-win32：提供 iproxy.exe、idevice_id.exe、ideviceinfo.exe。通过 Scoop 安装：

  root@kitploit:~

  scoop install libimobiledevice
  

  或使用 MSYS2：

  root@kitploit:~

  pacman -S mingw-w64-x86_64-libimobiledevice
  

  确保这三个 .exe 文件在 PATH 中（或放在 ioscpy.exe 旁边）。用 idevice_id -l 检查，应打印出设备 UDID。

2. 构建工具链

• Rust 并选择 MSVC 工具链：从 rustup.rs 安装。
• Visual Studio Build Tools 并包含 C++ 工作负载（openh264 解码器会通过 cc 编译一个小型 C 库）。
• nasm 需在 PATH 中：openh264 的汇编器（scoop install nasm）。

3. 构建与运行

git clone https://github.com/lautarovculic/ioscpy
cd ioscpy
cargo build --release --manifest-path host/Cargo.toml
.\host\target\release\ioscpy.exe --list      # 确认设备被识别
.\host\target\release\ioscpy.exe             # 打开镜像窗口

如果希望使用 MJPEG 路径而非 H.264，请传递 --mjpeg。如果 openh264 构建失败，请确认 nasm 在 PATH 中。

初次触摸

在注销或重新连接后，在通过主机控制之前，请先在手机屏幕上物理触摸一次。iOS 只信任来自真实触控板的触摸事件，因此第一次真实触摸才能让注入的触摸事件通过。只需操作一次，之后主机便可接管控制。

控制

• 鼠标：单击以触摸，单击并拖动以滑动。
• 打字：按键会发送到当前聚焦的输入框，支持任何 Mac 键盘布局。重音符号和表情符号通过剪贴板传递。
• Esc：返回。
• Cmd+J、Cmd+L、Cmd+T、Cmd+R：主页、锁定、应用切换器、旋转。
• Cmd+A、Cmd+C、Cmd+V、Cmd+X、Cmd+Z：全选、复制、粘贴、剪切、撤销。剪贴板双向同步，因此在手机上按 Cmd+C 的内容可以到达 Mac。
• 回车、退格、制表符、方向键：对应的编辑键。

在 Linux 和 Windows 上，使用 Ctrl 替代 Cmd 执行这些快捷键（Ctrl+C、Ctrl+V 等）；剪贴板依然双向同步。

旋转手机将旋转并调整镜像的大小。

已测试环境

主机：

• Debian，KDE/Wayland
• Ubuntu 26.04，GNOME/Wayland
• Arch Linux，BSPWM
• Windows 11 x64

设备：

ioscpy 在上述设备上开发和测试。手头没有有根设备或所有 iOS 版本，因此按布局覆盖不完整：

如果你在其他 iPhone、iOS 版本或越狱上运行 ioscpy，请帮助补充。有根和其他 iOS 版本尤其需要测试。

• 如果运行正常，请添加一行包含你的设备、iOS 版本、布局和注入框架，并提交拉取请求。
• 如果运行失败，请提供足够详细的信息以便修复：
  • iPhone 型号和 iOS 版本
  • 越狱和布局（Dopamine、palera1n 无根或有根、roothide）
  • 注入框架（ElleKit、Substitute、Substrate）
  • ioscpy --debug 的输出
  • 出问题的部分（屏幕、触摸、键盘、剪贴板、安装等）

项目布局

host/       Rust 主机端 CLI（macOS、Linux 和 Windows）
device/     iOS 软件包（Theos）：守护进程、ctl、插件、jbcompat、打包
protocol/   通信格式文档，与代码保持同步
scripts/    设备部署、注销、日志和诊断辅助脚本
docs/       架构、越狱兼容性、故障排除、发布

构建

make host-release        # macOS 主机端二进制
make device-rootless     # 无根 .deb（Dopamine、palera1n 无根、/var/jb）
make device-rootful      # 有根 .deb（palera1n 有根、/）
make release             # 主机端加两个设备变体

需要 Rust、Theos（$THEOS）、libimobiledevice（idevice_id、iproxy）、ldid 和 dpkg-deb。

适用范围

ioscpy 用于在桌面上通过 USB 线控制你自己的越狱 iPhone，从 Mac、Linux（Debian、Ubuntu 和 Arch Linux）设备操作。

对于 Linux 主机，外部依赖与 macOS 相同：libimobiledevice 工具（iproxy、idevice_id、ideviceinfo）和 usbmuxd。

现在也支持 Windows，复用标准 iOS USB 工具，不替换任何驱动程序。但依然仅限越狱的 iPhone。