VMs
A VM is a virtual machine with its own public IP address. You log in over SSH with your own key, from the addresses you list, and you can become root with sudo. The lease is paid in advance by the hour.
The key needs "VMs" under "Use for". You can also create and manage VMs on the console's VMs page.
Create a VM
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/vms \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $RETRY_KEY" \
-d '{
"class": "standard",
"hours": 4,
"ssh_public_keys": ["ssh-ed25519 AAAA… you@laptop"],
"allowed_cidrs": ["203.0.113.10/32"]
}'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, hourly price and stopped rate. |
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. |
hours | The lease to prepay, in whole hours. 1 to 168, default 1. Your trust tier can allow less. See Quotas and network. |
ssh_public_keys | Required. 1 to 10 public keys of type ssh-ed25519, ssh-rsa or ecdsa-sha2-nistp256. |
allowed_cidrs | Required. 1 to 20 address ranges that may connect over SSH. IPv4 ranges must be /8 or narrower, IPv6 ranges /32 or narrower. |
metadata | Optional. Up to 20 string pairs for your own use. |
Creating needs an Idempotency-Key. The answer is 202 with the VM. Its id starts with vm_. SSH keys and address ranges are set when the VM is created. There is no call to change them afterwards.
Poll GET /v1/vms/{id} until state is running. Then public_ip holds the address. A VM that isn't running within 10 minutes is deleted, ends as failed, and isn't charged.
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","hours":1,"ssh_public_keys":["ssh-ed25519 AAAA…"],"allowed_cidrs":["203.0.113.10/32"]}'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.
Log in
ssh pwc@203.0.113.25- The user is
pwc(thessh_userfield). It can runsudofor root. - Only key login works. Passwords and direct root login are off.
- Only TCP port 22 is open, and only to the ranges in
allowed_cidrs. - The image is Ubuntu 24.04 LTS.
You're root inside the VM, so what runs inside it is yours to secure. Outbound traffic follows the same rules as sandboxes. See Quotas and network.
The lease
- The
hoursyou ask for are held when you create the VM and charged in full once it first runs. If it never runs, the hold is released. prepaid_untilshows when the lease ends.- When the lease ends, the VM is stopped, not deleted. See Stopped VMs.
Renew
curl https://cloud.theyilabs.com/v1/vms/$VM/renew \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"hours": 2}'- A renewal is charged at once, at the VM's hourly price.
- It adds the hours to the end of the current lease, or to now if the lease has already ended.
- The lease can't reach further ahead than your tier's longest lease. A renewal that would gets
409 quota_exceeded. - A VM can be renewed once it has run, also while it is stopped.
The console's "Renew for 1 hour" button does the same for one hour.
Stop, start, reboot, reinstall
Each is a POST to /v1/vms/{id}/{action} with an Idempotency-Key. The answer is 202.
| Action | What happens |
|---|---|
stop | Stops the VM. Prepaid time isn't refunded. The disk and IP address are kept, at the stopped rate. |
start | Starts a stopped VM. It needs prepaid time left. Without it you get 402 insufficient_funds, so renew first. |
reboot | Restarts a running VM. |
reinstall | Erases the system disk and installs it fresh. The public IP address stays. The body must be {"confirm_destroy_disk": true}. The VM must be running or stopped. |
One action at a time. Another one while it's still in progress gets 409 conflict. If a reboot or reinstall is interrupted and its outcome is unclear, Yi Cloud doesn't repeat it. It stops the VM, closes it off, and sets error_code to action_uncertain. Delete it and create a new one, or contact us.
Stopped VMs
- A stopped VM keeps its disk and public IP address and is charged the stopped rate (
stopped_micro_per_hour) for them. It's charged for each full hour stopped. When it starts again or is deleted, the last part of an hour is charged by the second. - A VM stays stopped for at most 24 hours. Then it's deleted.
- If the balance, or the spend limit of the key that created it, can't cover the stopped rate, it's deleted.
Serial output
GET /v1/vms/{id}/serial returns the last 64 KiB of the VM's boot serial output as text. Use it when SSH doesn't answer. It's read live and not stored.
Delete
curl -X DELETE https://cloud.theyilabs.com/v1/vms/$VM \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Deleting destroys the disk and everything on it. It can't be undone. The state moves to deleting, then deleted.
Cost
| What | How it's charged |
|---|---|
| Lease | The hourly price times hours, in full once the VM first runs. |
| Renewal | The hourly price times hours, at once. |
| Stopped | The stopped rate, per full hour, the last part by the second. |
Stopping doesn't refund the lease. The receipt for one VM is at GET /v1/vms/{id}/receipt, as JSON or with ?format=csv. See Billing and receipts.
List
GET /v1/vms returns your workspace's 200 most recent VMs, newest first, including deleted ones.