# 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](/docs/concepts/catalog): 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](/docs/concepts/lifecycle). |
| `auto_stop_after_seconds` / `auto_stop_at` | The [auto-stop](/docs/concepts/auto-stop) duration and the current deadline. |
| `idle_sleep_after_seconds` / `idle_since` / `idle_sleep_at` / `last_active_at` | The [idle-sleep](/docs/concepts/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](/docs/guides/setup-scripts) operation, when one was given. |
| `environment` | The [environment](/docs/guides/environments) 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](/docs/guides/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](/docs/guides/ports) or [install an SSH key](/docs/guides/ssh); exposed ports are served only through VMYard's HTTPS edge. What a machine may reach outbound is its [egress policy](/docs/guides/networking), `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](/docs/guides/api-keys) and always by its creator's current role.

## Copies of a machine

A stopped machine can be pushed as a [snapshot](/docs/guides/snapshots) or saved as a [template](/docs/guides/templates); a running machine can be [forked](/docs/guides/fork-and-restore), 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.