How OpenSafari compares
tl;dr — OpenSafari controls the real Safari inside Xcode Simulator via WebKit Remote Debugging Protocol — the same way OpenChrome controls real Chrome via CDP. No middleware, no bundled browsers. Just direct protocol access to the actual Safari.app.
Headless Capabilities
OpenSafari runs fully headless on CI — no display server, no mouse focus, no Simulator.app window required. See docs/headless-architecture.md for the full technical design. For Universal Link channel recipes (Notes paste-and-tap, captureLogs, channel matrix), see docs/recipes/universal-link-channels.md.
✅ Supported and stable. ⚠️ Partially supported — see linked docs for current status and limitations.
Stability commitments (stable vs opt-in vs experimental) are catalogued in docs/simhid-ios26-investigation.md#stability-commitments.
Headless input vs other iOS automation tools
See docs/private-apis.md for the SimulatorKit contract, the daily sentinel CI that detects BC breaks, and the rollback plan if Apple changes symbols.
For CI setup recipes (GitHub Actions, Buildkite, GitLab CI), see docs/ci-recipes.md.
Long-running MCP sessions are soak-tested nightly — see memory-soak workflow.
What is OpenSafari?
Imagine testing your e-commerce site on iPhone 17e, iPhone 17, iPhone 17 Pro Max, and iPad — all at the same time, already logged in, with an AI agent that automatically finds iOS-specific bugs. That's OpenSafari.
You: Check our checkout flow for mobile issues across all iPhone sizes
AI: [4 parallel simulators, all devices simultaneously]
iPhone 17e: ⚠ Credit card input triggers iOS auto-zoom (font-size: 14px)
iPhone 17: ✓ Layout OK
iPhone 17 PM: ⚠ "Place Order" button only 38×32px (below 44px touch target)
iPad: ⚠ Shipping form hidden behind keyboard when focused
Time: 8s | All screenshots captured and analyzed.
Core Architecture
OpenSafari follows the same direct-protocol philosophy as OpenChrome:
OpenChrome: CDPClient → Chrome DevTools Protocol → Real Chrome
OpenSafari: SafariClient → WebKit Remote Debugging Protocol → Real Safari in Simulator
No middleware. No bundled browsers. Direct connection.
Claude Code / AI Agent (MCP Client)
│
│ JSON-RPC (stdio / HTTP)
▼
┌─────────────────────────────────────┐
│ OpenSafari MCP Server │
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ Simulator │ │ Safari │ │
│ │ Manager │ │ Client │ │
│ │ (simctl) │ │ (WebKit │ │
│ │ │ │ Protocol) │ │
│ └──────┬──────┘ └──────┬───────┘ │
│ │ │ │
│ boot/shutdown navigate/click │
│ rotate/appear screenshot │
│ multi-device DOM/JS/cookies │
│ │ │ │
│ ┌──────▼────────────────▼───────┐ │
│ │ Xcode Simulator(s) │ │
│ │ ┌────────┐ ┌────────┐ │ │
│ │ │ iPhone │ │ iPhone │ ... │ │
│ │ │ SE │ │ 16 PM │ │ │
│ │ │ Safari │ │ Safari │ │ │
│ │ └────────┘ └────────┘ │ │
│ └───────────────────────────────┘ │
│ │
│ ┌─────────────────────────────┐ │
│ │ Shared Infrastructure │ │
│ │ (from OpenChrome) │ │
│ │ • Security (sanitizer, │ │
│ │ domain guard, audit) │ │
│ │ • Watchdog (event loop, │ │
│ │ disk, health endpoint) │ │
│ │ • Orchestration (workflow │ │
│ │ engine, parallel workers)│ │
│ │ • Session persistence │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
Key Features
1. Real Safari, Real Bugs
OpenSafari controls the actual Safari.app inside Xcode Simulator via WebKit Remote Debugging Protocol — not a bundled approximation. Every iOS-specific quirk is faithfully reproduced:
- iOS auto-zoom on inputs with
font-size < 16px position: fixedbehavior with real software keyboard100vhviewport height inconsistencies with address bar- Safe area insets (notch, home indicator) on real device frames
color-schemedark mode forced rendering- Touch target minimum size requirements (44×44px)
2. Parallel Multi-Device Testing
Test across multiple devices simultaneously with a single command:
opensafari serve --devices "iphone-17e,iphone-17,iphone-17-pro-max,ipad-pro"
# 4 simulators boot in parallel
# Each gets its own Safari instance + WebKit Protocol connection
# All share login state via cookie injection
3. Persistent Login Sessions
Log in once, test forever. Cookies and localStorage are extracted directly from the real Safari session:
# First time: login captured from real Safari
opensafari auth save --site myapp.com
→ Exports cookies via WebKit Protocol Network.getAllCookies
→ Saves to ~/.opensafari/auth/myapp.json
# Every subsequent run: auto-restored
opensafari serve
→ Injects cookies via Network.setCookie into each simulator's Safari
→ All simulators start already logged in
Auth profiles are JSON files stored under ~/.opensafari/auth/. Each profile contains the site name, capture timestamp, current URL, cookies, cookie domain groups, localStorage, and sessionStorage needed to restore login state. On POSIX systems, OpenSafari creates new auth profile directories as private 0700 directories and profile files as private 0600 files, then updates profiles with an atomic same-directory replacement.
Delete saved login state with opensafari auth delete myapp.com, or remove the matching ~/.opensafari/auth/myapp.com.json file.
4. iOS-Specific Auto-Detection
Built-in QA checks that run on real Safari — no approximation:
5. MCP Native
Works with any MCP client — Claude Code, Cursor, VS Code, or custom agents:
// .mcp.json
{
"mcpServers": {
"opensafari": {
"command": "npx",
"args": ["-y", "opensafari-mcp", "serve"]
}
}
}
6. Shared DNA with OpenChrome
OpenSafari shares battle-tested infrastructure with OpenChrome:
Tools
Core Tools (Tier 1)
Device Management (Tier 1)
App Lifecycle (Tier 2)
Auth Tools (Tier 3)
Parallel & Orchestration (Tier 2)
iOS QA Engine (Tier 3)
Flutter QA Workflow
OpenSafari drives Flutter apps running in the iOS Simulator using the same native-app tools used for UIKit/SwiftUI. The only wrinkle is that Flutter's accessibility tree is lazy — it only populates when an assistive technology (VoiceOver, XCTest) connects. OpenSafari auto-activates it so widget labels are queryable.
Auto-activation (no app changes required)
app_tree, app_query, app_inspect, app_tap_element, app_wait_for, and app_assert_element all call ensureSemanticsActive() before reading the accessibility tree. The activator:
- Quick-checks the tree — if it already has ≥5 nodes, semantics is already active.
- Toggles
com.apple.Accessibility.AccessibilityEnabledviaxcrun simctl spawn defaults write— this triggers Flutter'sSemanticsBindingwithout enabling VoiceOver spoken feedback. - Polls the tree (up to 3s) until it populates, or falls back gracefully if activation never succeeds.
Recommended workflow
// 1. Boot simulator and launch the Flutter app
await device_boot('iPhone 16');
await app_launch({ bundleId: 'com.example.flutterApp' });
// 2. Terminate Safari if it's running — its background elements can
// dominate the macOS AX tree and hide Flutter widgets.
await app_terminate({ bundleId: 'com.apple.mobilesafari' });
await app_switch_app({ bundleId: 'com.example.flutterApp' });
// 3. Read the tree — Flutter Semantics nodes appear automatically.
const tree = await app_tree({ max_depth: 5 });
// 4. Query widgets by label, identifier, or role.
const button = await app_query({ label: 'Login' });
const email = await app_query({ identifier: 'email-field' });
Making widgets queryable
Release builds
Approach A (simctl defaults write) works for both debug and release builds. If a release app still reports an empty tree, add the explicit opt-in to main.dart:
void main() {
WidgetsFlutterBinding.ensureInitialized();
SemanticsBinding.instance.ensureSemantics(); // enable for OpenSafari QA
runApp(const MyApp());
}
For debug/profile builds, flutter_connect + flutter_widget_tree additionally expose the Dart VM Service, which returns the full Flutter widget hierarchy (including render-tree nodes that never reach the native AX bridge).
See docs/troubleshooting.md for common failure modes (empty trees, missing labels, Safari shadowing). For stateful semantic mobile QA, selector quality, settle policy, and scenario v2 guidance, see docs/mobile-semantic-qa.md.
Quick Start
# Install
npm install -g opensafari-mcp
# Run (stdio mode — for MCP clients like Claude Code)
opensafari serve
# HTTP mode (binds to 127.0.0.1 and requires a bearer token for /mcp)
OPENSAFARI_HTTP_TOKEN="replace-with-a-random-token" opensafari serve --http 3100
# With all tool tiers exposed
opensafari serve --all-tools
# With specific devices auto-booted
opensafari serve --devices "iphone-17e,iphone-17-pro-max"
# With auth state
opensafari serve --auth ~/.opensafari/auth/mysite.json
HTTP transport security
HTTP mode listens on 127.0.0.1 by default. The /health endpoint is unauthenticated, but /mcp requires Authorization: Bearer <token> unless you intentionally pass --http-insecure-local for local-only testing. Provide the token with OPENSAFARI_HTTP_TOKEN or --http-token; OpenSafari never prints the token value.
Browser CORS for /mcp is restricted to local origins (localhost, 127.0.0.1, ::1) plus any comma-separated origins passed with --http-allow-origin. Use --http-host only when you intentionally need a non-loopback bind.
HTTP mode also blocks high-risk MCP tools that execute page/app code or move authentication material: javascript, flutter_evaluate, auth_save, auth_restore, and cookies. Stdio mode is unchanged. To intentionally expose those tools over HTTP, start with --http-enable-high-risk-tools or set OPENSAFARI_HTTP_ENABLE_HIGH_RISK_TOOLS=1; allowed and blocked high-risk HTTP calls are audit-logged with sensitive arguments redacted.
OPENSAFARI_HTTP_TOKEN="$OPENSAFARI_HTTP_TOKEN" opensafari serve --http 3100
curl -H "Authorization: Bearer $OPENSAFARI_HTTP_TOKEN" \
-H "Content-Type: application/json" \
http://127.0.0.1:3100/mcp \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
MCP Client Configuration
// Claude Code: .mcp.json
{
"mcpServers": {
"opensafari": {
"command": "npx",
"args": ["-y", "opensafari-mcp", "serve"]
}
}
}
// Claude Desktop: claude_desktop_config.json
{
"mcpServers": {
"opensafari": {
"command": "npx",
"args": ["-y", "opensafari-mcp", "serve", "--all-tools"]
}
}
}
Tool Tiers
Tools are organized into 3 tiers for progressive disclosure. The default surface is Tier 1 (12 tools, ~4.5 KB of schema); higher tiers are opt-in so the tools/list payload stays small for MCP clients that load every tool schema into model context.
Every registered tool must have an explicit entry in src/config/tool-tiers.ts; tools without one fall back to Tier 3 (enforced by tests/unit/tool-tier-drift.test.ts).
Migration note (0.7.x): earlier releases exposed Tier 2 (132 tools, ~22k tokens of schema) by default. If you relied on Tier 2 tools being listed without configuration, set
OPENSAFARI_TOOL_TIER=2in the server environment or pass--all-tools.
Programmatic API
import { createServer } from 'opensafari-mcp';
// Start with the default Tier 1 tool surface over stdio
await createServer();
// Expose all tool tiers immediately (same as opensafari serve --all-tools)
await createServer({ allTools: true });
// Or start with HTTP transport
await createServer({
transport: 'http',
port: 3100,
authToken: process.env.OPENSAFARI_HTTP_TOKEN,
});
WebKitClient
Direct WebKit protocol access for custom automation:
import { WebKitClient } from 'opensafari-mcp';
const client = new WebKitClient({ host: 'localhost', port: 9322 });
await client.connect({ retries: 5, retryDelay: 2000 });
// Navigate and evaluate
await client.navigate({ url: 'https://example.com', waitUntil: 'load' });
const title = await client.evaluate<string>('document.title');
// Screenshot (returns PNG buffer)
const png = await client.screenshot();
// Cookies
const cookies = await client.getCookies();
await client.setCookies([{ name: 'key', value: 'val', domain: '.example.com',
path: '/', expires: -1, httpOnly: false, secure: false }]);
// DOM interaction
await client.click('#submit-btn');
await client.type('#email-input', '[email protected]');
await client.disconnect();
SimulatorManager
Programmatic simulator lifecycle control:
import { SimulatorManager } from 'opensafari-mcp';
const manager = new SimulatorManager();
// Boot a device
const device = await manager.boot('iPhone 17 Pro');
console.log(device.udid, device.state); // "XXXX-..." "Booted"
// Open Safari
await manager.openUrl(device.udid, 'https://example.com');
// List booted devices
const booted = await manager.listBooted();
// Shutdown
await manager.shutdown(device.udid);
Requirements
- macOS (Xcode Simulator is macOS only)
- Xcode with iOS Simulator runtime installed
- Node.js >= 18
- ios-webkit-debug-proxy —
brew install ios-webkit-debug-proxy
WebInspector Proxy Configuration
OpenSafari uses ios_webkit_debug_proxy to bridge WebKit Remote Debugging from Xcode Simulator. The proxy is auto-started by the device_boot tool — no manual setup is needed in most cases.
Default Ports
Port 9322 is deliberately offset from Chrome DevTools (9222) so OpenSafari and OpenChrome can run simultaneously.
Custom Port
Set the OPENSAFARI_PROXY_PORT environment variable to use a different device port:
# Use port 9500 instead of the default 9322
OPENSAFARI_PROXY_PORT=9500 opensafari serve
Port resolution order:
- Explicit
portoption (programmatic use) OPENSAFARI_PROXY_PORTenvironment variable- Default: 9322
Multi-Session Usage
Multiple Claude Code sessions can share the same proxy. When a session detects a healthy proxy already running on its target port, it reuses it instead of starting a new one. When the owning session exits, only its own proxy is terminated — other sessions' proxies remain unaffected.
Input Backend Selection
OpenSafari dispatches native input (app_tap, app_swipe_native,
app_scroll_native, app_double_tap, app_type_text, app_key_input)
through a 5-tier fallback chain and surfaces the selected path in each tool
result via a backend field. Coordinate and element-targeted tap tools also
surface whether the interaction was verified by a post-action AX-tree check.
Transport success alone is no longer treated as interaction success when no
observable UI effect can be confirmed. app_tap_element now applies the same
contract after it falls back from ax-press to a coordinate backend: callers
get verified: false with effect: "verification_unavailable" when the AX
proof is unavailable, or a typed TAP_NO_EFFECT result when the UI stays
unchanged after the dispatched tap.
See docs/headless-architecture.md for the
decision flowchart and the full scenario matrix. Tool responses also include
_meta: { backendKind, headless, deviceId } so CI can assert
_meta.headless === true.
Raw bridge consumers can now ask for the same foreground diagnostics directly:
dist/ax-bridge context --device <udid> [--expect-bundle <bundle>] [--require-match true]dist/sim-hid-bridge context <udid> [--expect-bundle <bundle>] [--require-match true]
dist/sim-hid-bridge tap|swipe also appends classification, verified,
frontmost, and expectedBundleMatched to its JSON result so downstream QA can
tell the difference between a clean in-app tap and a wrong-foreground outcome.
Example tool result:
{
"status": "tapped",
"x": 100,
"y": 200,
"deviceId": "…",
"backend": "simhid",
"verified": true,
"effect": "subtree_changed",
"_meta": { "backendKind": "simhid", "headless": true, "deviceId": "…" }
}
Raw dist/ax-bridge Contract
dist/ax-bridge is a Node.js wrapper that sits in front of the compiled
Swift binary dist/ax-bridge-native (Mach-O). The wrapper intercepts
--help / -h before argument validation, runs ensureSemanticsActive()
for tree-read commands by default (opt out with --ensure-semantics off),
then delegates every other invocation unchanged to dist/ax-bridge-native.
Bridge resolution order:
dist/ax-bridge-nativenext to the script (standard installed layout)- Swift interpreter fallback — only when
dist/ax-bridge.swiftis present
Contract: commands that cannot expose app content return a typed error code as JSON on stdout (exit 1) instead of an empty-success tree:
Example invocations:
# dump — success: full JSON accessibility tree on stdout, exit 0
node dist/ax-bridge dump --device booted
# dump — error: chrome-only tree after bootstrap, exit 1
# stdout: {"error":"...","code":"APP_CONTENT_NOT_EXPOSED"}
# query — success: matched elements on stdout, exit 0
node dist/ax-bridge query --device booted --label "Sign In"
# query — error: device not found, exit 1
# stdout: {"error":"...","code":"DEVICE_RESOLUTION_FAILED"}
# inspect — success: single element detail on stdout, exit 0
node dist/ax-bridge inspect --device booted --path "0/1/2"
# inspect — error: empty content root, exit 1
# stdout: {"error":"...","code":"DEVICE_CONTENT_ROOT_EMPTY"}
# press — success: {"ok":true,"code":"OK",...} on stdout, exit 0
node dist/ax-bridge press --device booted --path "0/1/2"
# context — success: foreground bundle info on stdout, exit 0
node dist/ax-bridge context --device booted
# context — expected bundle mismatch, exit 1
# stdout: {"error":"...","code":"EXPECTED_BUNDLE_MISMATCH"}
Note: The higher-level
app_*MCP tools provide the same semantics activation plus richer heuristics (retry, partial-tree promotion, and cross-session device resolution). Use the raw bridge for downstream harnesses that prefer direct CLI access without the MCP layer.
Focus-theft protection (OPENSAFARI_ALLOW_FOCUS_INPUT)
Tier 3 is default-deny. On Xcode 26+ with no Safari connection,
getInputBackend() throws HeadlessInputUnavailableError instead of
silently moving the physical mouse cursor. To re-enable the legacy
AppleScript/CGEvent fallback (for example, to automate a non-Safari native
app), opt in with an environment variable:
# Only set this if you understand the consequences — it WILL move your
# mouse cursor and bring Simulator.app to the foreground.
OPENSAFARI_ALLOW_FOCUS_INPUT=1 opensafari serve
Accepted values are 1 and true; anything else is ignored. When the
opt-in is honored, a one-time warning is logged to stderr at the first
tool call.
Relationship to OpenChrome
OpenSafari is the Safari/iOS counterpart to OpenChrome. Same philosophy, same architecture — different browser.
Together, they provide complete browser coverage — Chrome for desktop, Safari for iOS — both controlled by AI agents through MCP with direct protocol connections. No middleware, no bundled browsers.
Documentation
License
MIT
