What Is dsh-ios? An iOS Simulator for DeepSeek Harness

dsh-ios is an iOS Simulator and real-device control plugin installed into DeepSeek Harness (DSH): the agent can boot a device, build and run an Xcode project, drive the UI by accessibility identity or OCR text, read unified logs, and inspect processes, backtraces, and leaks, while the device screen renders as a live MJPEG stream in a sidebar panel you can tap, drag, rotate, or press Home on — and the same tools and panel also drive a real iPhone connected over USB. This article covers what dsh-ios is, its core features, how to install and enable it, typical usage, and common questions.

What Is dsh-ios?

dsh-ios solves the pain of switching between the Simulator, Xcode, and a terminal when debugging iOS apps: it folds the device screen, build-and-run, and UI automation into the DSH conversation, so the agent can see the pixels and you can take over at any moment. The positioning and facts below come from the official README (source):

dsh-ios (GitHub repository ZSeven-W/dsh-ios) is maintained by zseven-w, open source under the MIT license, published on npm as @zseven-w/dsh-ios, and is a tools-type plugin in the DSH Plugin ecosystem that requires macOS with Xcode installed. It splits simulator and device operations into 22 agent tools that return JSON (ios_sim_* plus ios_real_start_wda). Images never appear as picture blocks or screen-recording files: visual bytes reach the UI only through short-lived, HMAC-signed URLs served by the DSH webserver, so the browser never directly touches the simulator's streaming port. For a real device, WebDriverAgent is the workhorse — the plugin builds and launches it on the phone and tunnels its control and screen ports over loopback usbmux forwards, so the same tools, panel, cards, and status capsule then operate the iPhone.

What Are the Core Features of dsh-ios?

The core capability set centers on a live simulator and real device, 22 agent tools, an interactive sidebar, semantic UI automation, row-level verification, SwiftUI preview hot reload, and loopback-only secure transport: the agent can both see the screen and tap real controls, and every image byte travels over a protected signed channel. The features below come from the official README (source):

• Live simulator and real-device control: the device screen streams into the sidebar panel via MJPEG with tap, drag, rotate, and Home support; a real iPhone connected over USB works the same way.
• 22 agent tools: cover device boot and shutdown, screenshots, build and run, unified logs, UI tree export, element taps, list and feed row actions, OCR find and tap, SwiftUI preview hot reload, and process, backtrace, and leak inspection.
• Semantic UI automation: exports the hierarchy from the accessibility tree and taps by label or identifier; when the tree is empty or degenerate it falls back to Vision OCR to recognize text and tap it.
• List and feed row actions: turn deep accessibility snapshots into indexed rows and use parsed in-row counters to verify that a tap actually took effect.
• SwiftUI preview hot reload: generates a disposable host app, compiles previews into a dynamic library, and hot-swaps edits into the running simulator in about 2 to 5 seconds.
• Loopback-only secure transport: all traffic binds to the loopback address, routes require loopback peer and Host checks plus Fetch-Metadata and Origin validation, and HMAC capabilities expire within 10 minutes.

How to Install and Enable dsh-ios?

Before installing dsh-ios, confirm the machine is macOS with full Xcode and at least one iOS Simulator runtime installed; then add the plugin to a DSH web profile and launch the DSH Web UI to call the 22 tools in conversations. Commands and requirements below come from the official README (source):

1. Check the environment (recommended): dsh-ios depends on full Xcode on macOS (not just Command Line Tools). Verify with xcodebuild and simctl:

xcodebuild -version
xcrun simctl list devices available

2. Install from npm: run this from the DeepSeek Harness project root to add the plugin to the web profile, then start the Web UI:

dsh plugin --profile web add @zseven-w/dsh-ios@latest
dsh web

3. Confirm it is enabled: open the DSH Web UI and check Settings → Plugins to confirm dsh-ios is enabled; when the iOS Simulator panel entry appears in the sidebar, the plugin has loaded successfully.

4. Prepare optional dependencies: the AXe accessibility-tree tool can be installed with Homebrew, and Vision OCR compiles automatically on first use:

brew install cameroncooke/axe/axe

5. Update the plugin: rerunning the install command resolves the newest version on npm (the host's update command works too):

dsh plugin --profile web add @zseven-w/dsh-ios@latest

6. Uninstall the plugin: remove it in the host's plugin management, or run the remove command and restart:

dsh plugin remove @zseven-w/dsh-ios

Typical dsh-ios Usage

The typical dsh-ios flow is: discover devices → boot one and open the panel → let the agent drive the UI or build and run your project → iterate quickly with preview hot reload → connect a real iPhone when you need one, with the screen visible live on the right throughout. The steps below come from the official README (source):

1. Discover devices: ask the agent to list available simulators (USB-connected iPhones and their Developer Mode status also appear), then pick the device udid or name you want:

List the available simulators.  →  ios_sim_devices

2. Boot the device and open the panel: ask the agent to boot the simulator; the MJPEG stream starts and the iOS Simulator panel on the right shows the live screen. You can tap and drag directly on the video, or use the toolbar to rotate, screenshot, or press Home.

3. Let the agent drive the UI: pick the driving style for the situation — identity-driven via the accessibility tree plus element taps, text-driven via OCR find-and-tap when the tree is empty, or row tools for list-style apps:

Open Settings, then tap General.  →  ios_sim_interact

4. Build and run your project: hand the agent the path to an Xcode project or Swift package; it compiles, installs, and launches the app. Full builds take a few minutes, and once the app lands you see it live in the panel.

5. SwiftUI preview hot reload: ask the agent to start previews for a Swift package; every time you edit the source, the preview hot-swaps into the running simulator in about 2 to 5 seconds without a relaunch.

6. Connect a real iPhone over USB: plug the phone in, unlock it, and enable Developer Mode, then ask the agent to start WebDriverAgent; once built, the panel switches to the real device and the same tools operate the phone using its udid.

dsh-ios Troubleshooting

Common problems fall into four buckets — tools reporting that Xcode is required, missing AXe or OCR dependencies, real-device calls failing with a status, and the picture stopping on its own — diagnosed respectively via the environment, dependencies, panel status codes, and idle policy. The guidance below comes from the official README (source):

1. Tool calls report that the iOS Simulator needs macOS and Xcode: the symptom is every device tool returning an environment error. The cause is a macOS host with only Command Line Tools, or no Xcode at all. Fix: install full Xcode and an iOS Simulator runtime; on non-macOS hosts the tools are registered but cannot execute.

2. UI-tree tools report AXe missing: the symptom is ios_sim_ui_tree and ios_sim_tap_element failing with a missing dependency. The cause is that AXe is not installed. Fix: install it with Homebrew, or let the plugin download a pinned version on first use (verified by SHA-256), or point to your own binary with DSH_IOS_AXE_BIN.

3. Real-device calls fail with a status code: the symptom is the panel status showing device-locked, cert-untrusted, profile-expired, or tunnel-failed. The causes are a locked device, an untrusted certificate, an expired free signing profile, or a broken USB link. Fix: unlock the device, trust the WebDriverAgent certificate, rerun ios_real_start_wda to re-sign, and reconnect with a different cable.

4. The picture stops by itself: the symptom is the panel stream disappearing when nobody is using it. This is an idle policy rather than a crash — the stream stops automatically after about 5 minutes with zero consumers. Fix: invoking a tool or reopening the panel restarts it immediately, and a crashed stream restarts in the background within about 5 seconds.

Use Cases and Notes

dsh-ios suits users who want to do iOS development and verification inside DSH: letting the agent build and drive an app, inspect UI state and logs, iterate on SwiftUI interfaces quickly, or operate a real device right from the conversation. Suitability and limits below come from the official README (source):

Typical scenarios include in-conversation UI verification — the agent boots a simulator, operates the interface, and confirms with a screenshot; Xcode project build-and-run, handing the full build to the agent and watching it live in the panel; fast SwiftUI iteration with preview hot reload; real-device debugging after unlocking an iPhone; and crash and leak triage, where the agent reads unified logs and captures backtraces and leak summaries. The caveats to note: dsh-ios only supports macOS with full Xcode and at least one simulator runtime installed; a real device needs a USB cable, an unlocked screen (auto-lock off is recommended), and Developer Mode enabled on the phone; WebDriverAgent requires a local source checkout that the plugin builds itself rather than downloads; AXe and Vision OCR are optional dependencies that respectively serve identity taps and text taps; backtrace capability depends on Developer Mode (lldb attach), and without it the tool degrades to Xcode's sample engine; and free signing profiles expire every 7 days, so you rerun the real-device start tool to rebuild the signature.

Project Links

dsh-ios is an MIT-licensed open-source project maintained by zseven-w (ZSeven-W), evolving as DeepSeek Harness's iOS Simulator and real-device control plugin. To browse the full feature list, screenshots, and plugin information, visit the dsh-ios plugin detail page on this site: dsh-ios.

This page is an independent guide rewritten from the plugin's official README — for the authoritative documentation and the latest changes, defer to the source: ZSeven-W/dsh-ios. A plugin is third-party code that runs on your machine once installed; inclusion is not an endorsement — review the source before installing.