Concepts
Machines
What a VMYard machine is, how it is identified, what it is made of, and who may change it.
A machine is an isolated Linux environment that belongs to one organization. You create it from a plan, an image, and a region, then run commands in it, move files in and out of /work, expose its ports, and reach it over SSH.
Identity
| Field | What it is |
|---|---|
id | The machine's UUID. Use it in every API path. |
tenant_alias | A name fixed at creation (1–63 lowercase letters, digits, and -, starting with a letter). It never changes and is part of how VMYard correlates the machine with its host. |
name | The display name. It follows the same rules, defaults to the tenant alias, and can be changed with PATCH /v1/machines/{id} or vy rename. |
The CLI and SDK find accept a machine ID, a tenant alias, or a unique display name. The HTTP API takes IDs only.
What a machine is made of
| Field | Meaning |
|---|---|
plan | {id, version} of the plan: size, price, and backend. |
image | {id, version} of the image the disk starts from. |
region | {id, version} of the region it runs in. |
resources | cpu, memory_mib, and disk_gib. |
backend | kvm (virtual machines), docker (development only), or mock (tests). |
desired_state / observed_state | What you asked for and what VMYard last saw. See Lifecycle states. |
auto_stop_after_seconds / auto_stop_at | The auto-stop duration and the current deadline. |
idle_sleep_after_seconds / idle_since / idle_sleep_at / last_active_at | The idle-sleep window (null is off), the current idle window and when it ends, and the last observed activity. |
setup_operation_id | The setup script operation, when one was given. |
environment | The environment version the machine should have and whether it is installed; null without one. |
ssh | {host, port, user} once an SSH key is installed. See SSH. |
Selections are pinned by exact version. Renaming a plan or publishing a new image version never changes a machine that already exists.
The /work directory
Files you write through the API live under /work, and file paths are relative to it. Background-command logs are written there too. Files in /work are kept while the machine is stopped and are removed when it is deleted.
Networking
Nothing reaches a machine from outside unless you expose a port or install an SSH key; exposed ports are served only through VMYard's HTTPS edge. What a machine may reach outbound is its egress policy, internet or none, chosen when you create it and changeable later. Machines on the docker development backend have no network, so ports and SSH are not available there.
Roles
Organization members have one role each:
| Role | Read machines | Create, change, use, and delete machines | Webhooks | Manage billing |
|---|---|---|---|---|
| Owner | Yes | Yes | Yes | Yes |
| Admin | Yes | Yes | Yes | No |
| Operator | Yes | Yes | No | No |
| Billing | Yes | No | No | Yes |
| Viewer | Yes | No | No | No |
"Use" includes running commands, reading and writing files, ports, and SSH keys. An API key is further limited by its preset and always by its creator's current role.
Copies of a machine
A stopped machine can be pushed as a snapshot or saved as a template; a running machine can be forked, and a snapshot restored. Each copy is a new machine with its own ID and guest identity that keeps its source's tenant alias, so two machines can share a machine name. Its display name tells them apart, and forked_from_machine_id or restored_from_snapshot_id says where it came from.