Concepts

Lifecycle states

Desired and observed machine states, the actions that move between them, and how to read a machine that is in between.

A machine has two states. desired_state is what you asked for most recently. observed_state is what VMYard last confirmed on the machine's host. They differ while an operation is in flight, and the observed state is the one to trust.

Desired state

Value	Set by
`running`	Create, start, or restart.
`stopped`	Stop, including an auto-stop, idle sleep, or a stop because the balance ran out.
`deleted`	Delete.

Observed state

observed_state is an object with a state field:

`state`	Meaning
`absent`	No machine exists on a host yet, or it has been removed.
`provisioning`	The machine is being created.
`running`	It is up. Also carries `boot_id`, which changes on every boot.
`stopped`	It is stopped. Nothing is metered.
`degraded`	The host reported a problem with the machine.
`unknown`	VMYard could not confirm the machine's state.

json

{
  "desired_state": "running",
  "observed_state": { "state": "running", "boot_id": "c1a4e7f0-…" }
}

Actions

Action	Route	CLI	Result when it succeeds
Create	`POST /v1/machines`	`vy new`	Observed `running`. Emits `machine.ready`.
Stop	`POST /v1/machines/{id}/stop`	`vy stop`	Observed `stopped`. Emits `machine.stopped`.
Start	`POST /v1/machines/{id}/start`	`vy start`	Observed `running`. Emits `machine.started`.
Restart	`POST /v1/machines/{id}/restart`	`vy restart`	Observed `running` with a new `boot_id`. Emits `machine.started`. See Restart.
Delete	`POST /v1/machines/{id}/delete`	`vy rm`	The machine is confirmed gone. Emits `machine.deleted`.

Each action is an operation and needs an Idempotency-Key. When a lifecycle operation ends failed or correlation_miss, VMYard emits machine.error; see Webhooks.

Creates, starts, and restarts also pass billing admission: the balance, the spend cap, the trial rules, and the concurrency and start-rate limits. See Usage, billing, and limits.

Restart

A restart is one operation that reboots a running machine in place: every process in it ends, /work is kept, and it comes back ready. On VM hosts the VM reboots from its own disk; on Docker hosts the workload's processes end. Exposed ports, the SSH port, and the egress policy stay.

The machine never stops: its metered run stays open, no machine.stopped is sent, and its auto-stop deadline starts again. A retry with the same Idempotency-Key never reboots twice.

It succeeds only when the machine is running and ready with a boot_id different from the one before. A restart that kept the old boot_id ends correlation_miss; the machine stays running and usable. A host that can't restart its machines yet ends the operation failed with restart_unsupported: nothing changed and the machine kept running.

Reading a machine in between

Desired running, observed provisioning: a create is in progress. Wait for its operation.
Desired stopped, observed running: a stop is queued or running.
Observed degraded or unknown: don't assume the machine works. You can still delete it. Check its latest operation's error_code.
An operation succeeded but the state did not change: look at completed_but_unchanged; treat the change as not made.

Guest commands, file operations, port changes, and SSH key changes all need an observed running machine.