Typed Client

    Use createAgentDeviceClient() when you want to drive the daemon from application code instead of shelling out to the CLI.

    Basic usage

    import { createAgentDeviceClient } from 'agent-device';

const client = createAgentDeviceClient({
  session: 'qa-ios',
  lockPolicy: 'reject',
  lockPlatform: 'ios',
});

const devices = await client.devices.list({ platform: 'ios' });
const ensured = await client.simulators.ensure({
  device: 'iPhone 16',
  boot: true,
});

await client.apps.open({
  app: 'com.apple.Preferences',
  platform: 'ios',
  udid: ensured.udid,
  runtime: {
    metroHost: '127.0.0.1',
    metroPort: 8081,
  },
});

const snapshot = await client.capture.snapshot({ interactiveOnly: true });

await client.sessions.close();

    Android installFromSource()

    const androidClient = createAgentDeviceClient({ session: 'qa-android' });

const installed = await androidClient.apps.installFromSource({
  platform: 'android',
  retainPaths: true,
  retentionMs: 60_000,
  source: { kind: 'url', url: 'https://example.com/app.apk' },
});

await androidClient.apps.open({
  platform: 'android',
  app: installed.launchTarget,
});

console.log(installed.packageName, installed.launchTarget);

if (installed.materializationId) {
  await androidClient.materializations.release({
    materializationId: installed.materializationId,
  });
}

await androidClient.sessions.close();

    On Android, a successful installFromSource() response returns enough app identity to relaunch the installed app:

    • packageName
    • launchTarget

    If the daemon cannot determine installed app identity, the request fails instead of returning an empty success payload.

    URL source rules

    installFromSource() URL sources are intentionally limited:

    • Private and loopback hosts are blocked by default.
    • Archive-backed URL installs are only supported for trusted artifact services, currently GitHub Actions and EAS.
    • For other hosts, prefer source: { kind: 'path', path: ... } so the client downloads/uploads the artifact explicitly.

    Direct Android .apk and .aab URL sources can still resolve package identity from the downloaded install artifact.

    Need React or React Native expertise you can count on?

    Let's talk