kosa8 docs

Guides / kosa8 Cloud / Metrics, logs and labels

Metrics, logs and labels

Four things for running many sandboxes at once: what each one is using, what ran in it, a way to find it again, and a webhook when one ends without you deleting it or a command in it runs out of memory.

Metrics

curl -s https://api.kosa8.com/v1/sandboxes/sbx_…/metrics -H "Authorization: Bearer $KOSA8_API_KEY"
# {"metrics":{"id":"sbx_…","state":"running","cpus":2,"mem_mb":4096,"disk_gb":32,
#   "cpu_pct":48.7,"cpu_seconds":312.4,"mem_bytes":1342177280,"mem_pct":31.3,
#   "disk_bytes":2147483648,"net":{"out_frames":9120,"out_bytes":1203391,"in_frames":15003,"in_bytes":20311822},
#   "egress_denied":0,"at":"2026-11-14T12:00:00Z"}}

Logs

curl -s 'https://api.kosa8.com/v1/sandboxes/sbx_…/logs?limit=20' -H "Authorization: Bearer $KOSA8_API_KEY"
# {"id":"sbx_…","entries":[
#   {"at":"…","cmd":["pip","install","-r","requirements.txt"],"exit":0,"ms":8312,"stdout_tail":"…Successfully installed …"},
#   {"at":"…","cmd":["python","train.py"],"exit":137,"ms":40210,"stream":true,"stderr_tail":"Killed","oom":true}]}

Every command run in the sandbox, through the API or a direct exec, is logged on its host: when, the command (long arguments clipped), the exit code, how long it took, and the last 2 KiB of stdout and stderr. The newest 200 are kept, oldest first in the answer. The log lives on the sandbox's host, not in kosa8's database, and is removed with the sandbox. Commands inside a long-running process you started (a server's own requests) are not logged; only the commands you ran.

Labels

curl -s -X POST https://api.kosa8.com/v1/sandboxes \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"labels":{"customer":"acme","run":"eval-42"}}'

curl -s 'https://api.kosa8.com/v1/sandboxes?label=run=eval-42&label=customer' -H "Authorization: Bearer $KOSA8_API_KEY"

curl -s -X PUT https://api.kosa8.com/v1/sandboxes/sbx_…/labels \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' -d '{"labels":{"run":"eval-43"}}'

Webhooks

Subscribe as for any other event: POST /v1/webhooks {"url": …, "events": ["sandbox.killed", "sandbox.oom"]}. A new endpoint that names no events gets every event, these two included; an existing endpoint keeps the events it chose. See Webhook recipes for checking signatures.