> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Starter machine images

> The open-source AWS AMIs and GCP images Aspect publishes for Workflows CI runners, where they're published, how they're versioned, and what each variant contains.

export const gatedAccess = (user, group) => {
  const loggedIn = !!(user && user.loggedIn);
  const groups = user && user.tenantMetadata && user.tenantMetadata.docsGroups || [];
  if (loggedIn && (!group || groups.indexOf(group) >= 0)) {
    return "entitled";
  }
  return loggedIn ? "signed-in" : "anonymous";
};

export const GatedLink = ({access, href, group, children}) => {
  const note = group ? "Aspect Enterprise customers" : "free Aspect account";
  const muted = {
    fontSize: "0.85em",
    opacity: 0.7,
    whiteSpace: "nowrap"
  };
  if (access === "entitled") {
    return <a href={href}>{children}</a>;
  }
  if (access !== "signed-in") {
    return <span>
        <a href={"/login?redirect=" + encodeURIComponent(href)}>{children}</a>
        <span style={muted}> (sign in: {note})</span>
      </span>;
  }
  return <span>
      {children}
      <span style={muted}> ({note})</span>
    </span>;
};

Aspect publishes a set of pre-built machine images for Workflows CI runners, called *starter images*. They're open source, built with Packer, and the scripts that produce them live in [aspect-build/workflows-images](https://github.com/aspect-build/workflows-images).

Starter images let you stand up Workflows without first building an image of your own, which suits a trial or a first deployment. For production, we recommend building and maintaining your own image, so you control the OS and package versions and your security patching cadence. See [Custom machine images](/docs/aspect-workflows/enterprise/self-hosted/infrastructure/machine-images), and use the starter image Packer scripts as a reference.

## Current release

The latest starter image version is **`20260916-0`**.

|     | Where they're published                                                                                                             |
| --- | ----------------------------------------------------------------------------------------------------------------------------------- |
| AWS | Account `213396452403`, in `us-east-1`, `us-east-2`, `us-west-1`, `us-west-2`, `eu-central-1` and `eu-west-1`. The AMIs are public. |
| GCP | Project `aspect-workflows-images`. The images are readable by all authenticated users.                                              |

Images are versioned `YYYYMMDD-N`, where `N` is the build number for that day. A new version is published when base images are refreshed or packages change; versions are immutable, so pin one and bump it deliberately.

<Note>
  Debian 11 reached end of life on 2026-08-31 and has no starter images from `20260916-0` on. Previously published Debian 11 images still exist but receive no updates. Use Debian 12 or 13.
</Note>

## Image names

Every starter image is named:

```
aspect-workflows-<distro>-<variant>-<arch>-<version>
```

For example, `aspect-workflows-ubuntu-2404-kitchen-sink-amd64-20260916-0`. The architecture is `amd64` or `arm64`.

GCP images additionally belong to an image family named `aspect-workflows-<distro>-<variant>-<arch>`, with no version suffix. Resolving the family always gives you the newest image in it.

## Distributions

Every distribution below is published for both `amd64` and `arm64`, in every variant.

| Distribution      | `<distro>`    | AWS | GCP |
| ----------------- | ------------- | --- | --- |
| Amazon Linux 2    | `al2`         | ✓   | —   |
| Amazon Linux 2023 | `al2023`      | ✓   | —   |
| Debian 12         | `debian-12`   | ✓   | ✓   |
| Debian 13         | `debian-13`   | ✓   | ✓   |
| Ubuntu 22.04 LTS  | `ubuntu-2204` | ✓   | ✓   |
| Ubuntu 24.04 LTS  | `ubuntu-2404` | ✓   | ✓   |
| Ubuntu 26.04 LTS  | `ubuntu-2604` | ✓   | ✓   |

## Variants

Each variant builds on `minimal`, so pick the smallest one that satisfies your build.

| Variant        | Contents                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `minimal`      | Only what Aspect Workflows itself needs.                                                                           |
| `gcc`          | `minimal` plus a C and C++ toolchain.                                                                              |
| `docker`       | `minimal` plus Docker CE.                                                                                          |
| `kitchen-sink` | `minimal` plus Docker, the C and C++ toolchain, common build tools, and the libraries headless browser tests need. |

### minimal

The Workflows dependencies and a small set of recommended extras:

* `fuse`, required by the high-performance remote cache configuration.
* `git` and `git-lfs`, to fetch source and support repositories using LFS.
* `rsync` and `rsyslog`, used by runner bootstrap and system logging.
* `mdadm`, for RAID 0 across multiple NVMe drives.
* `patch` and `zip`, used by some rulesets, package managers, and Bazel's undeclared test outputs.
* The cloud monitoring agent: the CloudWatch agent on AWS, and the Ops Agent with `google-osconfig-agent` on GCP. AWS Debian images also install the SSM agent.

Packages already present in a base image aren't reinstalled, so the exact package list differs slightly per distribution.

### gcc

Everything in `minimal`, plus `g++` and the matching `libstdc++` development package for that distribution's default compiler. On Amazon Linux this is `gcc`, `gcc-c++` and `libstdc++-devel`.

### docker

Everything in `minimal`, plus Docker CE: `docker-ce`, `docker-ce-cli`, `containerd.io`, and the Buildx and Compose plugins. Amazon Linux uses its own `docker` package. The Docker service is enabled, so it starts on boot.

### kitchen-sink

Everything in `docker` and `gcc`, plus the build and test tooling most non-hermetic builds reach for:

* Build tools: `build-essential`, `clang`, `cmake`, `make`, `jq`, `yq`, `moreutils`.
* Development headers: `libssl-dev`, `zlib1g-dev`, `libyaml-dev`, `libzstd1`.
* Headless browser and GUI test libraries: GTK 2 and 3, ATK, NSS, CUPS, ALSA, `libxss1`, `libxtst6`, plus `Xvfb` and `xauth` for a virtual display.

<Note>
  <code>chromium</code> and Node.js are currently installed only on the AWS Ubuntu 24.04 and Ubuntu 26.04 <code>kitchen-sink</code> images. If you need them on another <code>kitchen-sink</code> image, [contact support](/contact) and we'll add them.
</Note>

The exact package set varies by distribution, since package names differ across Debian, Ubuntu and Amazon Linux releases. The authoritative list for any image is the `install_packages` block in its Packer file, for example [`aws/ubuntu-2404/kitchen-sink.pkr.hcl`](https://github.com/aspect-build/workflows-images/blob/main/aws/ubuntu-2404/kitchen-sink.pkr.hcl).

<Note>
  You may also see images with a <code>custom-0</code> variant on Ubuntu 24.04. They aren't starter images and can change without notice. Use one of the variants above.
</Note>

## Find an image

### AWS

List every starter image in the current release, in the region you deploy to:

```bash theme={null}
aws ec2 describe-images \
  --region us-east-2 \
  --owners 213396452403 \
  --filters "Name=name,Values=aspect-workflows-*-20260916-0" \
  --query 'sort_by(Images, &Name)[].[Name,ImageId,Architecture]' \
  --output table
```

Narrow it to one distribution and variant, and take the most recent version:

```bash theme={null}
aws ec2 describe-images \
  --region us-east-2 \
  --owners 213396452403 \
  --filters "Name=name,Values=aspect-workflows-ubuntu-2404-kitchen-sink-amd64-*" \
  --query 'reverse(sort_by(Images, &CreationDate))[0].[Name,ImageId]' \
  --output text
```

<Tip>
  AMIs are region-scoped, so query the region your runners launch in. If your region isn't in the published list above, copy the AMI into it with <code>aws ec2 copy-image</code>.
</Tip>

### GCP

List every starter image in the current release:

```bash theme={null}
gcloud compute images list \
  --project=aspect-workflows-images \
  --filter="name~20260916-0" \
  --format="table(name,family,architecture)"
```

Resolve the newest image in a family, which is the most reliable way to find the current version of one distribution and variant:

```bash theme={null}
gcloud compute images describe-from-family \
  aspect-workflows-ubuntu-2404-kitchen-sink-amd64 \
  --project=aspect-workflows-images \
  --format="value(name)"
```

## Use an image in Terraform

On AWS, look the AMI up by name and pass its ID to the runner group:

```tf images.tf theme={null}
data "aws_ami" "runner_image" {
  owners      = ["213396452403"] # Aspect's workflows-images account
  most_recent = true
  filter {
    name   = "name"
    values = ["aspect-workflows-ubuntu-2404-kitchen-sink-amd64-20260916-0"]
  }
}
```

On GCP, reference the image by name in the `aspect-workflows-images` project:

```tf images.tf theme={null}
data "google_compute_image" "runner_image" {
  project = "aspect-workflows-images"
  name    = "aspect-workflows-ubuntu-2404-kitchen-sink-amd64-20260916-0"
}
```

Then set `image_id` on the `resource_types` entry your runner groups reference (through their `resource_type`) to `data.aws_ami.runner_image.id` or `data.google_compute_image.runner_image.id`. See <GatedLink access={gatedAccess(user, "workflows-subscriber")} href="/docs/aspect-workflows/enterprise/self-hosted/reference/terraform-config-aws" group="workflows-subscriber">Terraform module configuration (AWS)</GatedLink> and <GatedLink access={gatedAccess(user, "workflows-subscriber")} href="/docs/aspect-workflows/enterprise/self-hosted/reference/terraform-config-gcp" group="workflows-subscriber">Terraform module configuration (GCP)</GatedLink>.

<Tip>
  Pin a specific version rather than resolving the newest image. Runner instances pick up a new image only when they're replaced, so an unpinned lookup makes the image your runners boot depend on when an instance last recycled.
</Tip>

## Keeping up to date

New versions are announced by tag in [aspect-build/workflows-images](https://github.com/aspect-build/workflows-images/tags). When a version fixes a security issue, the relevant [security advisory](/docs/security/advisories/index) names the first version that carries the fix.

To move a deployment, change the version in your `images.tf` and re-apply. Existing runner instances continue on the old image until they are replaced, so trigger an instance refresh if you need the change to take effect immediately.