Example Script
This example shell script demonstrates how to use the Corellium REST API to:
- Search for a device with a specified instance ID.
- If it's found, ensure the device is powered on.
- If it's not found, create a new device with a desired hardware and firmware and wait for it to be ready.
- Wait for the device to boot.
- Wait for the device's app subsystem to be ready.
- List the running apps on the device.
Pre-Requisites
-
Ensure the following binaries are installed on your local environment:
curl
jq
-
Set an environmental variable
CORELLIUM_API_TOKEN
with your API token. -
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 Business 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
.
- For On-Premise customers, use
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}"