@sdkrun/agent-runtime

The sdk.run simulator sandbox: a local MCP server and broker that lets AI agents run JavaScript against the live iOS SDK on a booted simulator (and against macOS through the Node-API bridge). No Xcode project, no build cycle, milliseconds of feedback, and with SimDeck a picture of what the code put on screen. Part of sdk.run.

Runs real native code. iOS snippets execute inside the host app on the simulator; macOS snippets execute with your user's privileges as if typed into a REPL. This is a local development tool — never expose the broker or server to untrusted callers, and review what your agent runs the same way you review what it commits.

macOS only (Xcode with an iOS simulator for ios), Node ≥ 24.

Usage

npx -y @sdkrun/agent-runtime ios

Boots an iOS simulator (or uses the booted one), downloads and installs the sdk.run host app once, and serves a broker on 127.0.0.1:7331. If SimDeck is installed the phone streams to your browser; https://sdk.run/sandbox goes live against the broker automatically.

# one-shot from the CLI (attaches to the running session, or starts one)
echo 'return UIDevice.currentDevice.systemVersion' | sdkrun-runtime run -

# HTTP, from anything on this Mac
curl -s -X POST 127.0.0.1:7331/run -H 'content-type: application/json' \
  -d '{"code":"return NSLocale.currentLocale.localeIdentifier"}'

# as an MCP server for your agent
claude mcp add agent-runtime -- npx -y @sdkrun/agent-runtime serve

Snippets for iOS are the body of an async function: return a value. In scope: rootVC (the root UIViewController), page and stage (a NativeScript Page / StackLayout for ad-hoc views), frame. Results come back as { ok, result, logs, ms } (ObjC objects by .description; NSArray/NSDictionary walked). Pass reset: true to dismiss whatever a previous snippet presented.

const a = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
  'Verified on device',
  'Created by a snippet.',
  UIAlertControllerStyle.Alert
);
a.addAction(
  UIAlertAction.actionWithTitleStyleHandler(
    'Nice',
    UIAlertActionStyle.Default,
    null
  )
);
rootVC.presentViewControllerAnimatedCompletion(a, true, null);
return 'presented';

MCP tools

• run_snippet { platform?: 'ios' | 'macos', code, reset?, timeout_ms?, pump_events_ms?, verify?, force? } — ios (default) evaluates on the simulator and returns { result, logs, error, ms } plus the simulator name and SimDeck URL; macos runs an ESM snippet on this Mac through @nativescript/macos-node-api (objc.import("AppKit"), export default the value; { result, stdout, stderr, error, crashed }). Every run is verified against the sdk.run oracle and the target OS version first (verify defaults to true): APIs that don't exist, or were introduced after that OS, block the run and return the report; force: true runs anyway.
• verify_snippet { platform?, code, os_version? } — the static check alone.
• runtime_info — simulator session (device, host, SimDeck URL) and macOS bridge report.

Isolation model

iOS snippets run inside the host app on the simulator: a hang is reported as a timeout, a crash takes down the host app (relaunch with sdkrun-runtime ios), never this process. macOS snippets run in a disposable child process: a native crash (SIGSEGV in the bridge) is reported as { crashed: true, signal } instead of killing the server, and runaway snippets are SIGKILLed at the timeout. Crash tolerance matters because autonomous agents call edge APIs by definition.

ObjC conventions: selectors camelCase-munge into one name (initWithContentRect:styleMask:backing:defer: → initWithContentRectStyleMaskBackingDefer); properties are plain property access without parentheses. On iOS, enum members follow the runtime's spelling (NSNumberFormatterStyle.CurrencyStyle); the verifier accepts it even though the index lists the Swift-style Currency.

Environment

• SDKRUN_IOS_PORT (7331), SDKRUN_IOS_UDID (simulator to use), SDKRUN_HOST_APP (a local build of the host instead of the pinned release), SDKRUN_ALLOWED_ORIGINS (extra browser origins for the broker; https://sdk.run and local dev are built in), SDKRUN_MCP_URL (oracle, default https://sdk.run/mcp).