Skip to content

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.

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

FieldValue
classRequired. A size id from GET /v1/compute/classes, which lists each size's vCPUs, memory, disk, hourly price and stopped rate.
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.
hoursThe lease to prepay, in whole hours. 1 to 168, default 1. Your trust tier can allow less. See Quotas and network.
ssh_public_keysRequired. 1 to 10 public keys of type ssh-ed25519, ssh-rsa or ecdsa-sha2-nistp256.
allowed_cidrsRequired. 1 to 20 address ranges that may connect over SSH. IPv4 ranges must be /8 or narrower, IPv6 ranges /32 or narrower.
metadataOptional. 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.

  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","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 ​

sh
ssh pwc@203.0.113.25
  • The user is pwc (the ssh_user field). It can run sudo for 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 hours you 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_until shows when the lease ends.
  • When the lease ends, the VM is stopped, not deleted. See Stopped VMs.

Renew ​

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

ActionWhat happens
stopStops the VM. Prepaid time isn't refunded. The disk and IP address are kept, at the stopped rate.
startStarts a stopped VM. It needs prepaid time left. Without it you get 402 insufficient_funds, so renew first.
rebootRestarts a running VM.
reinstallErases 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 ​

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

WhatHow it's charged
LeaseThe hourly price times hours, in full once the VM first runs.
RenewalThe hourly price times hours, at once.
StoppedThe 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.