Skip to main content

​
Overview

Android instances provide on-demand Android emulators in the cloud. You can create, list, retrieve, and delete instances programmatically using the SDK.

​
Creating an Instance

1

Basic Instance Creation

Create an Android instance with default settings:
import Limrun from '@limrun/api';

const client = new Limrun({
  apiKey: process.env.LIM_API_KEY,
});

const instance = await client.androidInstances.create();
console.log('Instance ID:', instance.metadata.id);
console.log('State:', instance.status.state);
2

Wait for Ready State

Use the wait parameter to block until the instance is ready:
const instance = await client.androidInstances.create({
  wait: true,
});

// Instance is now in 'ready' state
console.log('ADB URL:', instance.status.adbWebSocketUrl);
3

Configure Instance Settings

Customize timeouts, region, and metadata:
const instance = await client.androidInstances.create({
  wait: true,
  metadata: {
    displayName: 'My Test Device',
    labels: {
      env: 'production',
      team: 'qa',
    },
  },
  spec: {
    region: 'us-west',
    inactivityTimeout: '10m',
    hardTimeout: '1h',
  },
});

​
Instance Type

The AndroidInstance type contains metadata, spec, and status information: 
interface AndroidInstance {
  metadata: {
    id: string;
    createdAt: string;
    organizationId: string;
    displayName?: string;
    labels?: { [key: string]: string };
    terminatedAt?: string;
  };

  spec: {
    inactivityTimeout: string;
    region: string;
    hardTimeout?: string;
  };

  status: {
    token: string;
    state: 'unknown' | 'creating' | 'assigned' | 'ready' | 'terminated';
    adbWebSocketUrl?: string;
    endpointWebSocketUrl?: string;
    errorMessage?: string;
    targetHttpPortUrlPrefix?: string;
  };
}

​
Listing Instances

List all Android instances with optional filters: 
for await (const instance of client.androidInstances.list()) {
  console.log(instance.metadata.id, instance.status.state);
}

​
Getting an Instance

Retrieve a specific instance by ID: 
const instance = await client.androidInstances.get('instance-id-here');

console.log('Display Name:', instance.metadata.displayName);
console.log('State:', instance.status.state);
console.log('Created:', new Date(instance.metadata.createdAt));

​
Deleting an Instance

Terminate an instance when you’re done: 
await client.androidInstances.delete('instance-id-here');
console.log('Instance deleted');

​
Connecting to an Instance

Once an instance is ready, use createInstanceClient to interact with it: 
import { createInstanceClient } from '@limrun/api';

const instance = await client.androidInstances.create({ wait: true });

const instanceClient = await createInstanceClient({
  adbUrl: instance.status.adbWebSocketUrl!,
  endpointUrl: instance.status.endpointWebSocketUrl!,
  token: instance.status.token,
});

// Take a screenshot
const screenshot = await instanceClient.screenshot();
console.log('Screenshot data URI:', screenshot.dataUri);

// Start ADB tunnel
const tunnel = await instanceClient.startAdbTunnel();
console.log('ADB connected on port:', tunnel.address.port);

// Install an APK
await instanceClient.sendAsset('https://example.com/app.apk');

// Clean up
tunnel.close();
instanceClient.disconnect();
await client.androidInstances.delete(instance.metadata.id);

​
Advanced: Reuse Existing Instances

Prevent duplicate instances by reusing existing ones with matching labels: 
const instance = await client.androidInstances.create({
  reuseIfExists: true,
  metadata: {
    labels: {
      app: 'my-app',
      version: 'v1.2.3',
    },
  },
  spec: {
    region: 'us-west',
  },
});

// Returns existing instance if one with same labels and region exists

​
Advanced: Initial Assets

Install apps during instance creation: 
const instance = await client.androidInstances.create({
  wait: true,
  spec: {
    initialAssets: [
      {
        kind: 'App',
        source: 'URL',
        url: 'https://example.com/app.apk',
      },
      {
        kind: 'App',
        source: 'AssetName',
        assetName: 'my-app-v1.2.3',
      },
    ],
  },
});
Instances are automatically terminated after inactivityTimeout (default: 3 minutes) or hardTimeout if specified.
Use labels to organize instances by environment, team, or application version for easier filtering.

Build docs developers (and LLMs) love

Get started for freeTalk to us