Quickstarts
Your first pod
Deploy a CPU pod from a public image, wait until it runs, run a command inside it, and terminate it so billing stops.
A pod is one container on one machine, with the hardware you choose. It keeps running until you stop or terminate it, and it is billed per second while it runs.
Before you start
| Variable | Value |
|---|---|
API_KEY | sk_… (your project API key) |
API_BASE_URL | https://api.hayonix.ai/v1 |
INFERENCE_BASE_URL | https://api.hayonix.ai/v1 |
The samples take three inputs: IMAGE (default busybox:1.37.0), SKU (default cpu-2c-4gb, a small CPU machine) and REGION. GET /v1/pods/hardware lists every SKU, its price and where it can be launched now.
Deploy the pod
The pod runs sleep infinity so the container keeps running: when a pod's command exits, the pod is exited. volume: null asks for no persistent volume.
POD_ID=$(
jq -n --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" '{
name: "quickstart",
image: $image,
command: ["sleep", "infinity"],
hardware: {sku: $sku, gpu_count: 0},
region: $region,
volume: null
}' |
curl -sS --fail-with-body "$API_BASE_URL/pods" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d @- |
jq -r .id
)
echo "created $POD_ID"The call returns at once with the pod in its first state; placing it, pulling the image and starting the container happen in the background.
Wait until it runs
The SDK waiters poll the pod until it reaches running, and stop with an error if it reaches a state it cannot leave by itself (failed, exited).
for _ in $(seq 1 300); do
STATE=$(curl -sS --fail-with-body "$API_BASE_URL/pods/$POD_ID" \
-H "Authorization: Bearer $API_KEY" | jq -r .status.state)
[ "$STATE" = running ] && break
case "$STATE" in failed|exited|terminated) echo "pod $STATE"; exit 1 ;; esac
sleep 2
done
echo "state: $STATE"Run a command in it
exec runs a command in the container and waits for it, with a time limit of up to 120 seconds and at most 1 MiB of output per stream. For an interactive shell use SSH or the console's terminal.
curl -sS --fail-with-body "$API_BASE_URL/pods/$POD_ID/exec" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"command": ["uname", "-a"], "timeout_seconds": 10}' |
jq -r '"exit code: \(.exit_code)", (.stdout | rtrimstr("\n"))'Reset it
A reset recreates the container from its image on the same host: everything written to the container disk is gone, while volumes, the pod's addresses and its settings are kept. A restart (/restart) keeps the container disk instead.
# A reset recreates the container from its image: the container disk is fresh, volumes stay.
run() {
jq -n --arg cmd "$1" '{command: ["sh", "-c", $cmd], timeout_seconds: 10}' |
curl -sS --fail-with-body "$API_BASE_URL/pods/$POD_ID/exec" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d @- |
jq -r '.stdout | rtrimstr("\n")'
}
run 'echo scratch > /tmp/scratch.txt'
curl -sS --fail-with-body -X POST "$API_BASE_URL/pods/$POD_ID/reset" \
-H "Authorization: Bearer $API_KEY" >/dev/null
until [ "$(curl -sS --fail-with-body "$API_BASE_URL/pods/$POD_ID" \
-H "Authorization: Bearer $API_KEY" | jq -r .status.state)" = running ]; do sleep 2; done
echo "after reset: $(run 'cat /tmp/scratch.txt 2>/dev/null || echo "container disk is fresh"')"Terminate it
Terminating destroys the container and, unless you ask to keep it, the pod's volume. Billing stops at once. Stopping instead keeps volumes (which are still billed) so you can start the pod again later.
terminate() {
curl -sS --fail-with-body -X POST "$API_BASE_URL/pods/$POD_ID/terminate" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{}' >/dev/null
echo "terminated $POD_ID"
}
trap terminate EXITNext
- How compute is billed: running, stopped and terminated.
- Storage and volumes: what survives a stop, a reconfiguration and a terminate.