---
lastModified: 2026-10-13
---

# Images

An image is a whole disk that a run boots. Jinn's **bases** are images. A run makes a new image of its own disk when its function sets `output_image`. The next run can boot that image, so files, installed packages and settings last from run to run.

```sh
$ jinn images
img_8b2f04d6e1a93c75f0e2d418     run_3d9e1c07a5b28f64e0d71c92   812.4 MB  disk  51.5 GB  2026-10-13 09:41
debian-12-20261013-5e0c7a14      base                           498.7 MB  disk   4.3 GB  2026-10-13 06:12
```

`GET /v1/images` returns the same: the account's images, newest first, then the bases.

| Field | Value |
|---|---|
| `id` | `img_…`, or the base's name. |
| `base` | `true` for one of Jinn's bases. |
| `run`, `function` | The run that saved it, and its function. |
| `external_reference` | The run's `external_reference`. |
| `bytes` | Its compressed size: what is stored and billed. |
| `disk_bytes` | The size of its disk. |
| `sha256` | The SHA-256 of the compressed image. |

## Save a disk

Set `"output_image": true` in the function. The run then saves its disk when it ends:

- when a `finish` succeeds, after the output files are uploaded;
- when Jinn stops it with `timeout`, `credit`, `suspended`, `maintenance` or `provider`, as the disk was.

A run that fails before it is ready, fails with `input`, `setup` or `infrastructure`, or is finished as failed, saves nothing.

Before the disk is saved, the VM discards unused blocks and shuts down cleanly, within 2 minutes. A VM that does not shut down in time is stopped, and its disk is saved as it is, as after a power cut. The run's `output.image` names the new image.

```sh
$ jinn finish run_3d9e1c07a5b28f64e0d71c92
run_3d9e1c07a5b28f64e0d71c92 succeeded
image img_8b2f04d6e1a93c75f0e2d418
```

An image never changes. Each run from it that saves makes a new image; delete the old one when you no longer need it.

## Boot an image

Name the image in the function's `image`, or in a run's `image`:

```sh
$ jinn run go-sandbox --image img_8b2f04d6e1a93c75f0e2d418
```

- The disk grows to the run's size (see [sizes](/environment#sizes)). An image's disk keeps the size of the run that saved it, so boot it on that size or a larger one. A smaller size refuses it with `image_too_large`.
- `/workspace/in` and `/workspace/out` start empty in every run. Everything else on the disk is as the image left it.
- Setup runs again. Commands that are safe to repeat cost only a moment: `apt-get install` of an installed package does nothing.
- An image that does not boot fails the run with `input`.

## Make your own base

To skip setup's time in every run, run setup once and save the result:

1. Publish a function with your setup and `"output_image": true`, and no agent.
2. Run it and finish it: `jinn run base-builder`, then `jinn finish RUN`.
3. Publish your real function with `"image": "img_…"`, the image the run printed, and no setup.

## Delete an image

```sh
$ jinn image rm img_8b2f04d6e1a93c75f0e2d418
```

`DELETE /v1/images/{id}` does the same; it takes an `admin` key. A function that names a deleted image refuses new runs with `image_not_found`. A run still queued when its image is deleted fails with `input`. A run that has booted it is not affected.

## Storage

Images are kept until you delete them, and billed for their compressed `bytes`: $0.10 per GB-month. See [Pricing](/pricing#storage).

When the account's balance falls to its minimum, its images are kept free for 30 days. Its owners get an email when this starts, and again 7 days and 1 day before the end. Credit that lifts the balance above the minimum ends the 30 days and storage is billed again. After 30 days without credit, the account's images are deleted.