Skip to main content
The IosInstances resource provides methods to create, list, retrieve, and delete iOS instances.

​
Methods

​
create()

Create a new iOS instance. 
create(
  params: IosInstanceCreateParams,
  options?: RequestOptions
): APIPromise<IosInstance>

​
Parameters

​
reuseIfExists
boolean
If there is another instance with given labels and region, return that one instead of creating a new instance.
​
wait
boolean
Return after the instance is ready to connect.
​
metadata
object
Metadata for the iOS instance.
​
displayName
string
Human-readable display name for the instance.
​
labels
Record<string, string>
Key-value pairs for labeling the instance.
​
spec
object
Specification for the iOS instance.
​
region
string
The region where the instance will be created. If not given, will be decided based on scheduling clues and availability.
​
inactivityTimeout
string
After how many minutes of inactivity should the instance be terminated. Example values: "1m", "10m", "3h". Default is "3m". Providing "0" disables inactivity checks altogether.
​
hardTimeout
string
After how many minutes should the instance be terminated. Example values: "1m", "10m", "3h". Default is "0" which means no hard timeout.
​
clues
Array<Clue>
Scheduling clues to help determine optimal instance placement.Each clue object has:
  • kind: "ClientIP"
  • clientIp: IP address
​
initialAssets
Array<InitialAsset>
Assets to load when the instance starts.Each asset object has:
  • kind: "App"
  • source: "URL", "AssetName", or "AssetID"
  • url: URL to the app (when source is "URL")
  • assetName: Asset name (when source is "AssetName")
  • assetId: Asset ID (when source is "AssetID")
  • launchMode: "ForegroundIfRunning" or "RelaunchIfRunning" - specifies how to launch the app after installation. If not given, the app won’t be launched.
​
sandbox
object
Sandbox configuration.
​
xcode
object
Xcode sandbox configuration.
​
enabled
boolean
Enable Xcode sandbox.

​
Returns

​
metadata
object
required
​
id
string
required
Unique identifier for the instance.
​
createdAt
string
required
ISO 8601 timestamp when the instance was created.
​
organizationId
string
required
Organization ID that owns this instance.
​
displayName
string
Human-readable display name.
​
labels
Record<string, string>
Key-value labels attached to the instance.
​
terminatedAt
string
ISO 8601 timestamp when the instance was terminated.
​
spec
object
required
​
inactivityTimeout
string
required
Configured inactivity timeout.
​
region
string
required
Region where the instance is running.
​
hardTimeout
string
Configured hard timeout.
​
status
object
required
​
token
string
required
Authentication token for connecting to the instance.
​
state
string
required
Current state: "unknown", "creating", "assigned", "ready", or "terminated".
​
apiUrl
string
API URL for the instance.
​
mcpUrl
string
MCP (Model Context Protocol) URL for the instance.
​
endpointWebSocketUrl
string
WebSocket URL for endpoint connection.
​
targetHttpPortUrlPrefix
string
URL prefix for accessing HTTP ports on the instance.
​
errorMessage
string
Error message if the instance failed.
​
sandbox
object
​
xcode
object
​
url
string
Xcode connection URL.

​
Example

const instance = await limrun.iosInstances.create({
  wait: true,
  metadata: {
    displayName: "iPhone 15 Pro",
    labels: {
      environment: "production",
      team: "mobile"
    }
  },
  spec: {
    region: "us-east",
    inactivityTimeout: "15m",
    hardTimeout: "2h",
    clues: [
      {
        kind: "ClientIP",
        clientIp: "203.0.113.42"
      }
    ],
    initialAssets: [
      {
        kind: "App",
        source: "URL",
        url: "https://example.com/app.ipa",
        launchMode: "ForegroundIfRunning"
      }
    ],
    sandbox: {
      xcode: {
        enabled: true
      }
    }
  }
});

console.log(instance.metadata.id);
console.log(instance.status.state); // "ready"
console.log(instance.status.mcpUrl);

​
list()

List iOS instances with optional filters. 
list(
  query?: IosInstanceListParams,
  options?: RequestOptions
): PagePromise<IosInstancesItems, IosInstance>

​
Parameters

​
labelSelector
string
Labels filter to apply to instances to return. Expects a comma-separated list of key=value pairs (e.g., "env=prod,region=us-west").
​
region
string
Region where the instance is scheduled on.
​
state
string
State filter to apply to instances to return. Each comma-separated state will be used as part of an OR clause, e.g. "assigned,ready" will return all instances that are either assigned or ready.Valid states: "creating", "assigned", "ready", "terminated", "unknown"
​
pageSize
number
Number of items per page.
​
pageToken
string
Token for pagination.

​
Returns

Returns a paginated list of IosInstance objects.

​
Example

// List all ready instances
const instances = await limrun.iosInstances.list({
  state: "ready"
});

for await (const instance of instances) {
  console.log(instance.metadata.id, instance.status.state);
}

// List instances with specific labels in a region
const prodInstances = await limrun.iosInstances.list({
  labelSelector: "environment=production",
  region: "us-east"
});

​
get()

Get an iOS instance by ID. 
get(
  id: string,
  options?: RequestOptions
): APIPromise<IosInstance>

​
Parameters

​
id
string
required
The unique identifier of the iOS instance.

​
Returns

Returns an IosInstance object with the same structure as described in the create() method.

​
Example

const instance = await limrun.iosInstances.get("instance_456");

console.log(instance.metadata.displayName);
console.log(instance.status.state);
console.log(instance.status.apiUrl);

​
delete()

Delete an iOS instance. 
delete(
  id: string,
  options?: RequestOptions
): APIPromise<void>

​
Parameters

​
id
string
required
The unique identifier of the iOS instance to delete.

​
Returns

Returns a promise that resolves when the instance is deleted.

​
Example

await limrun.iosInstances.delete("instance_456");
console.log("Instance deleted successfully");

​
Type Definitions

​
IosInstance

The complete iOS instance object returned by the API. 
interface IosInstance {
  metadata: {
    id: string;
    createdAt: string;
    organizationId: string;
    displayName?: string;
    labels?: Record<string, string>;
    terminatedAt?: string;
  };
  spec: {
    inactivityTimeout: string;
    region: string;
    hardTimeout?: string;
  };
  status: {
    token: string;
    state: 'unknown' | 'creating' | 'assigned' | 'ready' | 'terminated';
    apiUrl?: string;
    mcpUrl?: string;
    endpointWebSocketUrl?: string;
    errorMessage?: string;
    targetHttpPortUrlPrefix?: string;
    sandbox?: {
      xcode?: {
        url?: string;
      };
    };
  };
}

​
IosInstanceCreateParams

Parameters for creating a new iOS instance. 
interface IosInstanceCreateParams {
  // Query parameters
  reuseIfExists?: boolean;
  wait?: boolean;
  
  // Body parameters
  metadata?: {
    displayName?: string;
    labels?: Record<string, string>;
  };
  spec?: {
    region?: string;
    inactivityTimeout?: string;
    hardTimeout?: string;
    clues?: Array<{
      kind: 'ClientIP';
      clientIp?: string;
    }>;
    initialAssets?: Array<{
      kind: 'App';
      source: 'URL' | 'AssetName' | 'AssetID';
      url?: string;
      assetName?: string;
      assetId?: string;
      launchMode?: 'ForegroundIfRunning' | 'RelaunchIfRunning';
    }>;
    sandbox?: {
      xcode?: {
        enabled?: boolean;
      };
    };
  };
}

​
IosInstanceListParams

Parameters for listing iOS instances. 
interface IosInstanceListParams {
  labelSelector?: string;
  region?: string;
  state?: string;
  pageSize?: number;
  pageToken?: string;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us