Example Script

This example shell script demonstrates how to use the Corellium REST API to:

1. Search for a device with a specified instance ID.
2. If it's found, ensure the device is powered on.
3. If it's not found, create a new device with a desired hardware and firmware and wait for it to be ready.
4. Wait for the device to boot.
5. Wait for the device's app subsystem to be ready.
6. List the running apps on the device.

Pre-Requisites

1. Ensure the following binaries are installed on your local environment:

   • curl
   • jq

2. Set an environmental variable CORELLIUM_API_TOKEN with your API token.

3. Set another environmental variable CORELLIUM_API_ENDPOINT.

   • For On-Premise customers, use https://<your_hostname>/api, where <your_hostname> is either the hostname or IP address of your Corellium appliance.
   • For Enterprise Cloud customers, use https://<your_domain>.enterprise.corellium.com/api, where <your_domain> is taken from the URL you use to access the Corellium web interface.
   • For Individual Cloud customers, use https://app.corellium.com/api.

Example Script

#!/bin/bash

set -e

required_env_vars=('CORELLIUM_API_ENDPOINT' 'CORELLIUM_API_TOKEN')
for var in "${required_env_vars[@]}"; do
  if [ -z "${!var}" ]; then
    printf 'Error: Environment variable %s is not set.' "${var}" >&2
    exit 1
  fi
done

create_instance() {
  curl -s -X POST "${CORELLIUM_API_ENDPOINT}/v1/instances" \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer ${CORELLIUM_API_TOKEN}" \
    -H 'Content-Type: application/json' -d \
    "{\"project\":\"${DEFAULT_PROJECT_ID}\", \
      \"name\":\"${DEFAULT_INSTANCE_NAME}\", \
      \"flavor\":\"${DEFAULT_INSTANCE_HARDWARE}\", \
      \"os\":\"${DEFAULT_INSTANCE_FIRMWARE}\"}"
}

get_instance() {
  inst_id="$1"
  curl -s -X GET "${CORELLIUM_API_ENDPOINT}/v1/instances/${inst_id}" \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer ${CORELLIUM_API_TOKEN}"
}

get_instance_agent_status() {
  inst_id="$1"
  curl -s -X GET "${CORELLIUM_API_ENDPOINT}/v1/instances/${inst_id}/agent/v1/app/ready" \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer ${CORELLIUM_API_TOKEN}"
}

handle_unexpected_state() {
  printf 'Unexpected state - instance %s is %s with taskState %s.\n' \
    "${instance_id}" \
    "${instance_state}" \
    "${instance_task_state}" \
    >&2
  exit 1
}

print_list_of_running_apps() {
  inst_id="$1"
  api_response_list_apps="$(curl -s -X GET "${CORELLIUM_API_ENDPOINT}/v1/instances/${inst_id}/agent/v1/app/apps" \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer ${CORELLIUM_API_TOKEN}")"
  printf 'List of running apps on instance %s:\n' "${inst_id}"
  echo "${api_response_list_apps}" | jq -r '.apps[] | select(.running == true) | .bundleID' | sort
}

start_instance() {
  inst_id="$1"
  curl -s -X POST "${CORELLIUM_API_ENDPOINT}/v1/instances/${inst_id}/start" \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer ${CORELLIUM_API_TOKEN}"
}

turn_instance_on_or_create_new_instance() {
  api_response_get_default_instance="$(get_instance "${DEFAULT_INSTANCE_ID}")"
  if [ "$(echo "${api_response_get_default_instance}" | jq -r '.errorID')" = 'null' ]; then
    printf 'Instance %s was found.\n' "${DEFAULT_INSTANCE_ID}"
    if [ "$(echo "${api_response_get_default_instance}" | jq -r '.state')" = 'off' ]; then
      printf 'Instance %s is off.\n' "${DEFAULT_INSTANCE_ID}"
      start_instance ${DEFAULT_INSTANCE_ID}
      printf 'Instance %s is powering on.\n' "${DEFAULT_INSTANCE_ID}"
    fi
  else
    printf 'Instance %s was not found.\n' "${DEFAULT_INSTANCE_ID}"
    printf 'Creating a new instance of %s hardware with %s firmware.\n' \
      "${DEFAULT_INSTANCE_HARDWARE}" \
      "${DEFAULT_INSTANCE_FIRMWARE}"
    api_response_create_instance="$(create_instance)"
    new_instance_id="$(echo "${api_response_create_instance}" | jq -r '.id')"
    printf 'Instance %s is creating.\n' "${new_instance_id}"
  fi
}

wait_for_instance_agent_to_be_ready() {
  inst_id="$1"
  api_response_agent_status="$(get_instance_agent_status "${inst_id}")"
  while [ "$(echo "${api_response_agent_status}" | jq -r '.ready')" != 'true' ]; do
    printf 'Waiting for agent to be ready.\n'
    sleep "${SLEEP_TIME}"
    api_response_agent_status="$(get_instance_agent_status "${inst_id}")"
  done
  printf 'The app subsystem on instance %s is ready.\n' "${inst_id}"
}

wait_for_instance_to_turn_on() {
  inst_id="$1"
  api_response_get_instance="$(get_instance "${inst_id}")"
  instance_state="$(echo "${api_response_get_instance}" | jq -r '.state')"
  instance_task_state="$(echo "${api_response_get_instance}" | jq -r '.taskState')"

  while [ "${instance_state}" != 'on' ] || [ "${instance_task_state}" != 'none' ]; do
    case "${instance_state}" in
      'booting' | 'creating' | 'rebooting')
        printf 'Waiting for instance to finish %s.\n' "${instance_state}"
        ;;
      'on')
        case "${instance_task_state}" in
          'none') ;;
          'stopping') handle_unexpected_state ;;
          *) handle_unexpected_state ;;
        esac
        ;;
      'deleting' | 'off') handle_unexpected_state ;;
      *) handle_unexpected_state ;;
    esac
    sleep "${SLEEP_TIME}"
    api_response_get_instance="$(get_instance "${inst_id}")"
    instance_state="$(echo "${api_response_get_instance}" | jq -r '.state')"
    instance_task_state="$(echo "${api_response_get_instance}" | jq -r '.taskState')"
  done
  printf 'Instance %s is on.\n' "${inst_id}"
}

# Define the default values for the instance
readonly DEFAULT_INSTANCE_ID='YOUR_INSTANCE_IDENTIFIER'
readonly DEFAULT_INSTANCE_FIRMWARE='18.0'
readonly DEFAULT_INSTANCE_HARDWARE='iphone16pm'
readonly DEFAULT_INSTANCE_NAME='REST_API_demo_device'
readonly DEFAULT_PROJECT_ID='YOUR_PROJECT_IDENTIFIER'

# Define time constant
readonly SLEEP_TIME='60'

command -v date > /dev/null && printf 'Starting the script at %s.\n' "$(date)"

new_instance_id=''
turn_instance_on_or_create_new_instance
instance_id="${new_instance_id:-${DEFAULT_INSTANCE_ID}}"

wait_for_instance_to_turn_on "${instance_id}"
wait_for_instance_agent_to_be_ready "${instance_id}"
print_list_of_running_apps "${instance_id}"