Instance spec and status

Every create call takes metadata and spec, and every instance reports its URLs and state in status. The spec tables cover iOS simulators and Android emulators; the lifecycle, status, timeout, and placement rules apply to Xcode and Gradle sandboxes too. Build-specific settings for sandboxes live in Build with Xcode and Build with Gradle. For what the fields mean in practice, start with Concepts; for the calls themselves, see SDKs and REST API.

Lifecycle states

Every iOS, Android, Xcode, and Gradle instance moves through the same lifecycle: creating while hardware is provisioned, assigned while it boots, ready when the URLs in status are usable, and finally terminated.

   creating ──┬──► assigned ──► ready ──► terminated
              │
              └──► (error) ──► terminated  (status.errorMessage set)

status.errorMessage is set when the instance terminated because of an error. A create call with wait: true returns once the instance is ready.

Status fields

A ready instance carries the URLs its data plane needs in status. Every URL authenticates with the instance token, never the API key.

The iOS and Android status blocks otherwise have the same shape. Reaching a server that runs inside the simulator (through targetHttpPortUrlPrefix) is the opposite direction from letting the device reach your machine; for that, see Connect to local services for iOS or Android.

Example create response

A successful Android create with wait: true returns the full instance resource. An iOS response has the same shape without adbWebSocketUrl:

{
  "metadata": {
    "id": "android_usw1_01krxvphn8e3rbeq0zewgw209a",
    "createdAt": "2026-05-18T19:52:42Z",
    "organizationId": "org_01kr52j...",
    "displayName": "android_usw1_01krxvphn8e3rbeq0zewgw209a",
    "labels": { "app": "demo", "session": "docs" }
  },
  "spec": {
    "inactivityTimeout": "10m0s",
    "region": "us-west2"
  },
  "status": {
    "state": "ready",
    "apiUrl":               "https://us-west2-1234567.limrun.net/v1/android_usw1_01krxv.../api",
    "adbWebSocketUrl":      "wss://us-west2-1234567.limrun.net/v1/organizations/org_01kr52j.../android.limrun.com/v1/instances/android_usw1_01krxv.../adbWebSocket",
    "endpointWebSocketUrl": "wss://us-west2-1234567.limrun.net/v1/organizations/org_01kr52j.../android.limrun.com/v1/instances/android_usw1_01krxv.../endpointWebSocket",
    "signedStreamUrl":      "https://console.limrun.com/signedStream?url=wss%3A%2F%2Fus-west2-1234567.limrun.net%2F...%2FendpointWebSocket#token=lim_...",
    "mcpUrl":               "https://us-west2-1234567.limrun.net/v1/android_usw1_01krxv.../mcp",
    "targetHttpPortUrlPrefix": "wss://us-west2-1234567.limrun.net/v1/organizations/org_01kr52j.../android.limrun.com/v1/instances/android_usw1_01krxv.../targetHttpPort",
    "token": "lim_...",
    "streamToken": "lim_..."
  }
}

The metadata and spec fields in the response:

Create parameters

Every create call, for any instance type, accepts these parameters next to spec:

Timeouts

Two timeouts end an instance without a delete call. Both take a duration string such as 1m, 10m, or 3h.

• spec.inactivityTimeout terminates the instance after this long without activity. The timer starts once the instance is ready. Omitted or '0', it uses your organization's default for the platform: new organizations start at 3 minutes for iOS and Android and 10 minutes for Xcode, and Gradle sandboxes default to 10 minutes. An organization default of 0 means instances are never terminated for inactivity. The maximum is 24h.
• spec.hardTimeout terminates the instance after this much wall-clock time, active or not. Default '0', no cap.

A terminated instance reports which one fired in status.terminationReason.

iOS spec

The spec fields accepted by iosInstances.create (TypeScript names; Python uses snake_case). The CLI flags for the same fields are in Run a simulator.

Android spec

The spec fields accepted by androidInstances.create. The CLI flags for the same fields are in Run an emulator.

The CLI's --os-version and --model flags set the OS version and model. It has no flags for the ClientIP and ClientLocation clues or for spec.sandbox.playwrightAndroid; set those from an SDK or REST.

Labels

metadata.labels is a free-form { [key: string]: string } map used for reuse, listing, and cleanup; Labels and reuse explains how. Avoid keys that could collide with metadata Limrun adds itself, such as the created-by: mcp label on instances the remote MCP server creates.

Placement

spec.jurisdiction (us, eu, or as) keeps an instance inside one jurisdiction. It is a hard constraint: creation fails when no region there has capacity.

spec.region is deprecated. It is a preference, such as eu-north1 or us-east1, that is tried first and overflows to other regions by proximity when the preferred ones are full. When both are omitted, Limrun places the instance by spec.clues and current availability.

jurisdiction is available in the TypeScript SDK and the CLI today; the Python and Go SDKs expose only region. The console's Analytics tab breaks down runtime minutes per platform and per region, which shows which regions your organization has used:

Client location clues

When you create an Android, iOS, Xcode, or Gradle instance through the REST API, supply the end user's coordinates as a ClientLocation clue to prefer a nearby region:

{
  "spec": {
    "clues": [
      {
        "kind": "ClientLocation",
        "clientLocation": {
          "latitude": 37.7749,
          "longitude": -122.4194
        }
      }
    ]
  }
}

Both coordinates are required and use decimal degrees. Latitude must be between -90 and 90, and longitude between -180 and 180, inclusive. Zero is valid. Missing or invalid coordinates return HTTP 400.

ClientLocation takes precedence over ClientIP regardless of their order in spec.clues. Without coordinates, pass { "kind": "ClientIP", "clientIp": "203.0.113.42" } to locate the end user by IP. For requests without either clue, Limrun uses available visitor coordinates first, then the connecting IP.

Location clues express a preference. spec.jurisdiction still constrains placement, and a full region can lead to creation in another eligible region. A specific spec.region overrides location clues. Use the REST payload above if your installed SDK does not expose ClientLocation yet.

Next steps