Skip to content

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.

sh
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.

FieldValue
classRequired. A size id from GET /v1/compute/classes, which lists each size's vCPUs, memory, disk and hourly price.
archamd64 (default) or arm64. GET /v1/compute/classes lists the architectures available.
poolOptional: 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_sThe 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_sDelete the sandbox after this many seconds without activity. 60 to 86,400, default 300.
metadataOptional. 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.

  1. GET https://cloud.theyilabs.com/v1/compute/regions lists the open regions (Singapore, Tokyo, US (Iowa), London, Sweden, Stockholm) and the machine families in each, with their architecture.
  2. GET https://cloud.theyilabs.com/v1/compute/machine-types?region=tokyo&family=n2 lists that family's machine types in the region: vCPUs, memory, disk, hourly price and stopped rate.
  3. Create with machine_type and region and leave out class:
sh
-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 ​

stateMeaning
requested, provisioning, bootingStarting.
readyReady for commands and files.
busyAt least one command is running.
deletingBeing deleted.
deletedGone. error_code says why, if it wasn't you.
failedIt 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 ​

sh
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}'
FieldValue
cmdRequired. A shell command line, up to 65,536 characters.
cwdWorking directory. Default /workspace.
envExtra environment variables, as {"NAME": "value"}. Each value up to 4,096 characters, about 16,000 in all.
timeout_sStop the command after this many seconds. 1 to 3,600, default 60.
streamtrue 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:

text
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_s runs out, and in any case when the sandbox's lifetime ends. A command stopped at its timeout_s answers exit_code: -1 with timed_out: true.
  • If a command fails because of Yi Cloud itself (not your command), the answer is 503 upstream_unavailable and 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:

sh
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.txt
  • path: where the file goes. A relative path starts at /workspace. The directory must already exist: otherwise the answer is 400 naming it (create it with mkdir -p first).
  • offset: where in the file this piece starts, in bytes.
  • truncate=true empties the file first. Use it for the first piece. Send the next pieces with truncate=false and the right offset.

The answer is 204.

Download with GET and a Range header of at most 64 KiB:

sh
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.txt

Without 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_s has passed since it became ready.
  • idle_timeout_s has 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 ​

sh
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_s is 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.