Sandboxes
A sandbox is its own virtual machine that you drive through the API. You run commands in it and read and write its files. Nothing can connect to it from outside. It is billed per second from when it's ready until it's deleted, with a 60-second minimum.
The key needs "Sandboxes" under "Use for". You can also create and use sandboxes on the console's Sandboxes page.
Create a sandbox
First request GET https://cloud.theyilabs.com/v1/compute/classes and choose an available size from classes. If the list is empty, compute cannot be created; use the Models API while no size is available. The create examples below require an available size and enough available credit.
RETRY_KEY=$(uuidgen)
curl https://cloud.theyilabs.com/v1/sandboxes \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $RETRY_KEY" \
-d '{"class":"small","timeout_s":1800,"idle_timeout_s":300}'Reuse this RETRY_KEY and body when retrying the same operation. Generate a new key for the next resource.
| Field | Value |
|---|---|
class | Required. A size id from GET /v1/compute/classes, which lists each size's vCPUs, memory, disk and hourly price. |
arch | amd64 (default) or arm64. GET /v1/compute/classes lists the architectures available. |
pool | Optional: pool-1, pool-2 or pool-3. Leave it out and Yi Cloud chooses. The pools open now are listed in pools in GET /v1/compute/classes. The old cloud field is gone and returns 400. |
timeout_s | The most the sandbox lives once it's ready, in seconds. 60 to 604,800, default 3,600. Your trust tier can allow less. See Quotas and network. |
idle_timeout_s | Delete the sandbox after this many seconds without activity. 60 to 86,400, default 300. |
metadata | Optional. Up to 20 string pairs for your own use, keys up to 60 characters, values up to 200. |
Creating needs an Idempotency-Key header. If the request fails on the network, send it again with the same key and the same body, and you get the same sandbox instead of a second one. See API reference.
The answer is 202 with the sandbox. Its id starts with sb_.
Choose a region and machine type
Instead of a class, you can pick the region and the exact machine type.
GET https://cloud.theyilabs.com/v1/compute/regionslists the open regions (Singapore, Tokyo, US (Iowa), London, Sweden, Stockholm) and the machine families in each, with their architecture.GET https://cloud.theyilabs.com/v1/compute/machine-types?region=tokyo&family=n2lists that family's machine types in the region: vCPUs, memory, disk, hourly price and stopped rate.- Create with
machine_typeandregionand leave outclass:
-d '{"machine_type":"n2-standard-4","region":"tokyo","timeout_s":1800,"idle_timeout_s":300}'The family sets the architecture, so you can leave out arch; a different arch returns 400. The L4 family (g2-standard-*) has one NVIDIA L4 and needs a GPU invitation. A resource created this way shows region and machine_type.
States
state | Meaning |
|---|---|
requested, provisioning, booting | Starting. |
ready | Ready for commands and files. |
busy | At least one command is running. |
deleting | Being deleted. |
deleted | Gone. error_code says why, if it wasn't you. |
failed | It never became ready. Nothing is charged. |
Poll GET /v1/sandboxes/{id} until state is ready. A sandbox that isn't ready within 10 minutes is deleted and ends as failed.
Run commands
curl https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX/exec \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cmd":"python3 --version","timeout_s":60}'| Field | Value |
|---|---|
cmd | Required. A shell command line, up to 65,536 characters. |
cwd | Working directory. Default /workspace. |
env | Extra environment variables, as {"NAME": "value"}. Each value up to 4,096 characters, about 16,000 in all. |
timeout_s | Stop the command after this many seconds. 1 to 3,600, default 60. |
stream | true for server-sent events instead of one JSON answer. |
Without streaming the answer is {"stdout": "…", "stderr": "…", "exit_code": 0}. If the output passes 1 MiB, the command is stopped and you get 400 invalid_request. Use stream: true for long output.
With streaming, each event's name matches the type in its data:
event: stdout
data: {"type":"stdout","text":"Python 3…\n"}
event: exit
data: {"type":"exit","exit_code":0}stderr events look like stdout. If the command can't be carried out, an error event with a code ends the stream.
Some rules:
- A sandbox runs at most 4 commands at once. A fifth gets
409 conflict. - Commands are never retried for you, so a command never runs twice by accident. If a call fails on the network, check the sandbox's state before you run it again.
- A command ends when its
timeout_sruns out, and in any case when the sandbox's lifetime ends. A command stopped at itstimeout_sanswersexit_code: -1withtimed_out: true. - If a command fails because of Yi Cloud itself (not your command), the answer is
503 upstream_unavailableand the message names the reason.
What's inside
Commands run as an ordinary user without sudo, in /workspace. That user can write to /workspace, its home directory /home/pwc, and /tmp. The rest of the file system is read-only. The image is Ubuntu 24.04 LTS with git, curl, build-essential, Python 3 and Node.js.
Outbound connections are limited to HTTP and HTTPS. Nothing reaches a sandbox from outside. See Quotas and network.
Files
Files move in pieces of up to 64 KiB.
Upload with PUT, the bytes as application/octet-stream:
curl -X PUT "https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX/files?path=/workspace/hello.txt&offset=0&truncate=true" \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @hello.txtpath: where the file goes. A relative path starts at/workspace. The directory must already exist: otherwise the answer is400naming it (create it withmkdir -pfirst).offset: where in the file this piece starts, in bytes.truncate=trueempties the file first. Use it for the first piece. Send the next pieces withtruncate=falseand the rightoffset.
The answer is 204.
Download with GET and a Range header of at most 64 KiB:
curl "https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX/files?path=/workspace/hello.txt" \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Range: bytes=0-65535" \
-o hello.txtWithout Range, you get the first 64 KiB. The Content-Range header ends with the file's full size, so you know how many more pieces to ask for.
Lifetime and idle time
A sandbox is deleted when the first of these happens:
- You delete it.
timeout_shas passed since it became ready.idle_timeout_shas passed without a command, a file call or a keepalive. A running command keeps it from going idle.- It stops reporting to Yi Cloud for more than 2 minutes.
To keep an idle sandbox, call POST /v1/sandboxes/{id}/keepalive. That resets the idle time. It doesn't extend timeout_s.
The sandbox's disk is destroyed with it. Copy out anything you want to keep before it ends.
Delete
curl -X DELETE https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"The answer is 202 and the state moves to deleting, then deleted. Once it's deleted, another delete just returns it. While it's still deleting, a delete with a new Idempotency-Key gets 409 conflict.
Cost
- When you create it, the hourly price times
timeout_sis held from the balance. - When it ends, it's charged per second from when it became ready until its deletion is confirmed, at least 60 seconds and at most
timeout_s. The rest of the hold is released. - If it never becomes ready, nothing is charged.
- If Yi Cloud failed every command you sent it and none ever ran, nothing is charged either.
A shorter timeout_s means a smaller hold. The receipt for one sandbox is at GET /v1/sandboxes/{id}/receipt, as JSON or with ?format=csv. See Billing and receipts.
List
GET /v1/sandboxes returns your workspace's 200 most recent sandboxes, newest first, including deleted ones.