# Prepare an image

Have kosem prepare an image that your agents use often, so that their environments start from it faster, and keep it up to date with its tag.

Have kosem prepare an image, such as your team's devcontainer, so that environments start from it faster. kosem pulls it once, keeps a copy ready for environments, and follows its tag. To do it, you need Owner, Editor or Environment Admin on the project or the organization, and, to share an organization's image with projects, Owner.

An image of the organization's serves the projects it's shared with. An image of a project serves only that project.

## Prepare an image [#prepare-an-image]

1. In your project or organization, click **Environments**, and then **Images**.
2. Click **New image**.
3. Enter the **Image**, with a tag or a digest, such as `ghcr.io/acme/devbox:2026.11`. kosem signs in to private registries with your [registries](/guides/environments/pull-private-images).
4. Optionally, enter a **Name (optional)**, which the image picker shows.
5. In an organization, select the projects it's shared with.
6. Click **Create image**.

The image shows as **Preparing** while kosem pulls and prepares it, and then **Ready**. Its size counts against your organization's image storage.

## Use it [#use-it]

Select it in an agent's environment settings, where the image picker lists prepared images, each saying whether it's ready. An image still preparing starts environments as any image would, until it's ready.

## Keep it up to date [#keep-it-up-to-date]

By default, kosem checks the image's tag every hour and prepares each new version it finds, so pushing a new version from CI is all it takes. It keeps the newest 3 versions, and deletes an older one once no environment runs it.

1. On the image's page, open **Updates**.
2. Turn **Follow its tag** on or off, and select the **Versions to keep**, from 1 to 10.
3. Click **Save updates**.

To prepare a new version now, without waiting for the next check, click **Refresh**.

## Delete an image [#delete-an-image]

Environments that run it keep running. At their next start they pull the image from its registry, which takes longer. kosem deletes what it prepared 7 days later.

## Related [#related]

- [Environments, images and registries](/concepts/environments#images)
- [Limits and quotas](/reference/limits#environments)
