# Regions, plans, and images

> The versioned catalog a machine is created from, how to read it, and how sizes are priced.

A machine is created from three catalog entries: a **plan** (size, price, and backend), an **image** (what the disk starts from), and a **region** (where it runs). Each entry has an `id` and a `version`, and a create request names both, so a later change to the catalog never changes an existing machine or a request you already sent.

## Reading the catalog

```sh tab="CLI"
vy plans
vy images
vy regions
```

```ts tab="TypeScript"
const [plans, images, regions] = await Promise.all([
  vy.catalog.plans(),
  vy.catalog.images(),
  vy.catalog.regions(),
]);
```

```python tab="Python"
plans, images, regions = vy.catalog.plans(), vy.catalog.images(), vy.catalog.regions()
```

```sh tab="curl"
curl "$VMYARD_API_URL/v1/plans" -H "Authorization: Bearer $VMYARD_API_KEY"
curl "$VMYARD_API_URL/v1/images" -H "Authorization: Bearer $VMYARD_API_KEY"
curl "$VMYARD_API_URL/v1/regions" -H "Authorization: Bearer $VMYARD_API_KEY"
```

Any member and any API key preset can read the catalog. The exact sizes, images, and regions on offer come from your VMYard deployment; always read them from the catalog rather than hard-coding them.

## Plans

A plan has a `name`, `version`, `cpu`, `memory_mib`, `disk_gib`, `backend`, and a `price` with `hourly` and `monthly` USD amounts. Machines are billed per second at the plan's hourly price while they run.

Sizes are priced like this:

| Size | Price per hour | Multiplier |
| --- | --- | --- |
| `small` | $0.015 | 0.5 |
| `default` | $0.030 | 1 |
| `large` | $0.060 | 2 |
| `xlarge` | $0.170 | about 5.67 |

The multiplier is a size's hourly price relative to `default`. Plan allowances and the trial are counted in `default`-size hours, so one hour of `small` uses half an hour of allowance. Trials can use only `small` and `default`. See [Usage, billing, and limits](/docs/guides/billing).

## Images

An image has a `name`, a `version`, and a content `digest`. A machine's disk starts from the exact image version you choose.

## Regions

A region has a `name`, a `version`, a `backend`, and a `capacity_status`. Choose a region whose backend matches the plan's backend.

## Choosing entries

The SDKs and CLI accept names or IDs and resolve them to the latest version for you. They default to the first plan, the first image, and the first region that matches the plan's backend.

```sh tab="CLI"
vy new --plan small --image ubuntu-24.04 --region eu-central --name dev
```

```ts tab="TypeScript"
const request = await vy.machines.buildCreateRequest({ plan: "small", name: "dev" });
console.log(request.plan, request.image, request.region); // exact {id, version} pairs
```

```python tab="Python"
request = vy.machines.build_create_request(plan="small", name="dev")
print(request["plan"], request["image"], request["region"])
```

The image and region names above are examples; use the names your catalog lists. With the HTTP API, send `plan`, `image`, and `region` as `{id, version}`, plus the plan's `resources` and `backend`. See [Create a machine](/docs/api/machines#create-a-machine).