Cloud machines

A cloud machine is a Windows or Linux computer that Sai hosts for one Tenant. Your backend creates it with an Organisation Key, sends work to it as the Tenant, and deletes it when the Tenant no longer needs it. Your customer installs nothing. The Organisation pays for the time the machine is on.

The steps below use curl and jq. Set these first:

export SAI_API_URL="https://api.simular.ai"
export SAI_ORG_KEY="sapi_..."
export ORG_ID="org_3f9a1c0b7e2d4a6f8c10"
export TENANT_ID="Xk2p9QzR4tLm8vNa3bCd"

Create the machine

MACHINE_ID=$(curl -s -X POST "$SAI_API_URL/v1/tenants/$TENANT_ID/machines" \
  -H "Authorization: Bearer $SAI_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"os\": \"windows\", \"name\": \"Riverside intake\", \"requestId\": \"$(uuidgen)\"}" \
  | jq -r .machineId)
echo "$MACHINE_ID"

os is windows or linux. Keep the requestId: if the call times out, send it again with the same requestId and the same body, and you get the same machine instead of a second one. See Retry a create.

If the create is refused, the answer says why: no credit, the Tenant's budget, its machine limit, or no capacity. The error table lists each one.

Wait until it is ready

The machine starts in provisioning. Get it until state is ready:

while :; do
  STATE=$(curl -s "$SAI_API_URL/v1/tenants/$TENANT_ID/machines/$MACHINE_ID" \
    -H "Authorization: Bearer $SAI_ORG_KEY" | jq -r .state)
  echo "$STATE"
  case "$STATE" in
    ready) break ;;
    failed) echo "No machine came up. Create another."; exit 1 ;;
    *) sleep 15 ;;
  esac
done

failed means no machine came up within 17 minutes. Cloud machine states lists every state.

Wait for ready only before the first message. After that, send whenever you need to: a message to a hibernated machine wakes it, and the run starts once the machine is up.

Send it work

Exchange the Organisation Key for a Tenant token, then send the message with the machine's id:

TENANT_TOKEN=$(curl -s -X POST "$SAI_API_URL/v1/orgs/$ORG_ID/tenants/$TENANT_ID/token" \
  -H "Authorization: Bearer $SAI_ORG_KEY" | jq -r .token)

SESSION=$(curl -s "$SAI_API_URL/v1/agents/message" \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"message\": \"Open Notepad and type hello\", \"machineId\": \"$MACHINE_ID\", \"wait\": false}" \
  | jq -r .sessionId)

Read the result from GET /v1/agents/events with the same Tenant token, as in the cURL example. Sending work to a cloud machine works the same as sending it to an enrolled one.

Delete the machine

curl -s -X DELETE "$SAI_API_URL/v1/tenants/$TENANT_ID/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $SAI_ORG_KEY"

The answer is 202 with { "state": "deleting" }. Sai deletes the machine and its disk, and the machine leaves the list when Sai is done. A delete cannot be undone.

A machine you don't delete keeps its disk and stays in the Tenant's list, hibernated, until you delete it or erase the Tenant.

What a cloud machine costs

The Organisation pays for the time a machine is on, at the hourly rate of its machineClass. The size follows the OS:

• A hibernated or deleted machine is not billed. There is no charge for its disk.
• The cost comes from the Organisation's credit and counts toward the Tenant's monthly budget.
• A machine hibernates 2 to 2.5 hours after its last activity, such as a message or a view of its live screen. It is billed until then, so each run on Windows costs about $0.42 of idle time on top of the run itself.

When a machine can't run