# Operating system images

> The operating system images an instance can run, and how to list the ones available to you.

Source: https://www.coritan.com/docs/cloud-compute/images/

An *image* is the operating system an instance starts from. You choose one in the **Operating system** section of the order page when you [create an instance](/docs/cloud-compute/create-an-instance/), and you can [rebuild](/docs/cloud-compute/rebuild/) onto another later. The API calls an image a *template*.

## Which images you can order

The order page lists every image that is ready to build, grouped by distribution with the newest release first. The images on offer change over time, so the order page and `GET /api/v1/client/vps/templates` are the list to trust.

| An image whose slug starts with | Is listed under |
| --- | --- |
| `ubuntu` | Ubuntu |
| `debian` | Debian |
| `almalinux` | AlmaLinux |
| `rocky` | Rocky Linux |
| `fedora` | Fedora |
| `centos` | CentOS Stream |
| `opensuse` | openSUSE |
| `arch` | Arch Linux |
| `alpine` | Alpine Linux |
| `freebsd` | FreeBSD |
| `windows` | Windows Server |

An image with any other slug is listed after these, under its own name.

## What the first boot sets up

We hand these settings to cloud-init in the image when we build the instance:

Default user
: The image's own default account, such as `root` or the distribution's usual user. The order page shows it as "Sign in as" and the **Access** tab shows it as **Username**.

Password
: A random password for the default user. We store it but do not show it. [Reset the password](/docs/cloud-compute/access/#reset-the-password) to get one you can read.

SSH keys
: The public keys you pasted in the **Settings** section of the order page, added to the default user's `authorized_keys`.

Hostname
: The hostname you chose in the **Settings** section.

Network
: The instance's primary address, gateway and mask, once an address is attached.

DNS resolvers
: `1.1.1.1` and `8.8.8.8`.

The dashboard also talks to the QEMU guest agent inside the instance, to read its operating system and addresses and to reset its password. The **Console** tab shows **Agent running** when the agent answers.

## Minimum sizes

An image can need a minimum disk and memory. The **Operating system** section of the order page shows a release the plan is too small for, with the reason under it, and does not let you pick it:

| Reason on the order page | What it means |
| --- | --- |
| `Needs at least 20 GB of disk` | The plan's disk is smaller than the image needs. |
| `Needs at least 2 GB of memory` | The plan's memory is smaller than the image needs. |
| **Plan too small** | No release of the distribution fits the plan. |

## With the API

`GET /api/v1/client/vps/templates` lists the images you can order or rebuild onto: every enabled image that at least one of our hosts can build now.

```bash
curl https://api.coritan.com/api/v1/client/vps/templates \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
[
  {
    "id": 7,
    "name": "Ubuntu 24.04 LTS",
    "slug": "ubuntu-24-04",
    "os_family": "linux",
    "os_version": "24.04",
    "default_username": "ubuntu",
    "min_cpu": 1,
    "min_memory_mb": 1024,
    "min_disk_gb": 10,
    "ready_nodes": 3
  }
]
```

`id`
: The value to send as `template_id` when you order or rebuild.

`name`, `slug`
: The image's name and its short identifier. The slug's first part names the distribution.

`os_family`
: `linux`, `windows` or `bsd`.

`os_version`
: The release, such as `24.04`.

`default_username`
: The user cloud-init sets up and the one you sign in as.

`min_cpu`, `min_memory_mb`, `min_disk_gb`
: The smallest plan the image runs on.

`ready_nodes`
: How many of our hosts can build the image now. An image that is ready somewhere may still not be ready in the location you want; an order for it there answers `422` with `OS template 7 is not ready in location 'fra'`.

## API

- `GET /api/v1/client/vps/templates`: OS templates ready for order/rebuild: enabled and ready on at least one active node (https://www.coritan.com/docs/api/reference/client/cloud-compute/#op-get-api-v1-client-vps-templates)