repository·main·Indexed 40 days ago
https://github.com/nativescript/simdeckA developer tool and macOS simulator control plane that allows developers to drive iOS simulators and Android emulators from IDEs or CLI. It includes a browser client, a Flutter Inspector package (simdeck_flutter_inspector), and a Swift-based Inspector Agent for exposing UIKit and SwiftUI view hierarchies.
The SimDeck VS Code Extension allows you to open the local SimDeck browser client directly within a VS Code webview panel.
By default, the extension attempts to connect to a service at http://127.0.0.1:4310. If a custom server URL is configured in your settings, it will use that instead. The extension manages the project service lifecycle by starting or reusing a service via simdeck service start only when required.
SimDeck provides several categories of interaction for mobile simulators:
simdeck/test.SimDeck is designed to connect your iOS device to a SimDeck server of your choice. The privacy model is based on the following principles:
SimDeck uses a random app-generated identifier for telemetry. It does not use device advertising identifiers, analytics profiles, or tracking for ads/marketing.
Excluded from telemetry:
To facilitate reconnection, the app stores server addresses, pairing tokens, and connection preferences locally on your device. This data is not transmitted to SimDeck.
All requests, pairing credentials, simulator controls, and stream negotiation data are sent only to the specific SimDeck server you have selected or paired with. SimDeck does not operate an intermediate service that intercepts this data.
When using simdeck describe or the browser inspector, SimDeck attempts to use the highest-fidelity source available, falling back in a specific order:
The response from the inspector includes metadata indicating which source was used and the reason for any fallbacks.
Most user actions follow a centralized request flow through the service, which is why the long-lived service architecture provides better performance than calling low-level simulator tools directly:
The SimDeck Inspector protocol is a lightweight JSON-based protocol used by in-app inspectors to publish UI trees and handle debug actions. It is primarily intended for developers building or debugging an inspector runtime.
Depending on the runtime, the protocol is delivered via different transports:
| Transport | Used by |
|---|---|
TCP on 127.0.0.1:47370-47402 | Swift in-app agent |
WebSocket /api/inspector/connect | NativeScript, React Native, Flutter, and other outbound runtimes |
Polling /api/inspector/poll plus /api/inspector/response | Fallback when WebSocket is unavailable |
All messages follow a specific JSON structure for Requests, Success responses, Errors, and Events.
Note: If the inspector was started with an auth token, all requests must include a matching top-level token field.
// Request Example
{
"id": 1,
"method": "View.getHierarchy",
"params": { "maxDepth": 4 }
}
// Success Response Example
{
"id": 1,
"result": { "roots": [] }
}
// Error Response Example
{
"id": 1,
"error": {
"code": -32004,
"message": "No view was found for id view:0x1234."
}
}
// Event Example
{
"event": "Inspector.connected",
"params": { "protocolVersion": "0.1" }
}When using --bind 0.0.0.0, you must provide an --advertise-host value that the remote client can resolve.
192.168.1.50) or local hostname (e.g., my-mac.local).Warning: If you bind to 0.0.0.0 but advertise localhost, remote browsers will attempt to connect to themselves instead of your SimDeck host.
simdeck --bind 0.0.0.0 --advertise-host my-mac.local --open
simdeck --bind 0.0.0.0 --advertise-host 192.168.1.50 --open
simdeck --bind 0.0.0.0 --advertise-host 100.101.102.103 --openSimDeck uses a live WebRTC stream to show the device in the browser. The encoding process depends on the platform:
-share-vid shared display surface and encoded on the Mac.SimDeck manages stream health by sending fresh frames and dropping stale ones if a client falls behind. Users can request refreshes via the UI.
View.hitTest or View.describeAtPoint) and frameInScreen values use UIKit screen points, not raw pixels.SimDeck provides two primary ways to interact with the running React Native app for debugging:
View.setProperty: A best-effort method to modify component properties. If the node resolves to a native host instance, the runtime uses setNativeProps(...). Note that the next React render cycle may overwrite these changes.View.evaluateScript: Executes JavaScript within the app context. This is useful for diagnostics as it runs with useful React Native objects in scope.To protect simulator sessions, set a repository secret (e.g., SIMDECK_PASSWORD) and pass it to the action via the session_password input.
When a password is provided, the action posts a SimDeck proxy link instead of the raw Cloudflare Tunnel URL. The daemon token is encrypted into the proxy payload, preventing access via the URL alone. To post raw tunnel links instead, set proxy_links: "false".
SimDeck is composed of several key pieces that work together to provide device inspection and control:
simdeck/test: A JS/TS wrapper designed for automation tasks.