# Images
Save a sandbox as an image and reuse it to start new sandboxes without reinstalling packages or setting up your
environment again.
An image saves the sandbox's disk, including installed packages, cloned repositories, and files. Every sandbox started
from that image has the same files and dependencies.
The examples use `$SANDBOX` for a sandbox ID and `$IMAGE` for an image ID, as described in the
[quickstart](quickstart.md).
## Save a sandbox as an image
Set up your sandbox, then save it as an image:
```bash
curl -X POST https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/snapshot \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata": {"name": "data-tools"}}'
```
The API returns `202` with the image in the `creating` state. Images are usually `ready` within a few seconds. Check
the status with `GET /v1/images/$IMAGE`.
The request body is optional. Use `metadata` to add your own labels.
The original sandbox continues running while Keln saves the image, and Keln bills it as usual.
## Start a sandbox from an image
Pass `image` instead of `template` when creating a sandbox:
```bash
curl -X POST https://sandbox.keln.ai/v1/sandboxes \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "'$IMAGE'"}'
```
The new sandbox starts with all files from the image and the same CPU and memory settings as the original sandbox. Set
`cpu` and `memory_mb` to use a different size.
The new sandbox's `image` field contains the image ID, and `template` identifies the template used by the original
sandbox.
You can also save a sandbox created from an image. Each image is independent, so deleting one doesn't affect other
images.
## What an image saves
| Kept | Not kept |
|---|---|
| All files on disk, including installed packages and files you created | Memory and running processes ([pause and resume](pause-resume.md) preserves these) |
| | Environment variables set through the API (`env`) |
| | Network policy and preview ports, which must be configured again |
**Important:** Images include any credentials or tokens saved on disk. Remove sensitive files before saving an image if
you don't want them copied into new sandboxes.
## List and delete images
```bash
curl https://sandbox.keln.ai/v1/images -H "Authorization: Bearer $KELN_API_KEY"
curl -X DELETE https://sandbox.keln.ai/v1/images/$IMAGE -H "Authorization: Bearer $KELN_API_KEY"
```
The API lists images in `creating`, `ready`, or `failed` states, newest first. Use `state` to filter the results.
Deleting an image stops its storage charges immediately. Existing sandboxes created from the image continue running.
Requests for the deleted image return `404`.
## Pricing
| Resource | Price |
|---|---|
| Stored images | $0.08 per GB-month |
Keln bills storage by the hour on the image's `size_bytes`, starting when the image becomes `ready` and ending when you
delete it.
For example, a 2.7 GB image costs about $0.22 per month.
Sandboxes created from images use standard sandbox pricing.
## Limits
| Limit | Default | Error |
|---|---|---|
| Images in `creating` or `ready` state | 20 per workspace | `429 image_limit` |
| Images being saved from the same sandbox simultaneously | 1 | `409 snapshot_in_progress` |
Failed images don't count toward the limit. Delete unused images to make room for new ones.
## Errors
| Status | Code | When |
|---|---|---|
| `409` | `sandbox_not_running` | The sandbox is paused or stopped. Resume it first. |
| `409` | `snapshot_in_progress` | An image of this sandbox is still being saved, or you tried to pause the sandbox while saving it. |
| `409` | `image_not_ready` | The image is still `creating` or has failed. |
| `404` | `image_not_found` | The image doesn't exist in this workspace. |
| `429` | `image_limit` | The workspace has reached its 20-image limit. |
Failed images have `state: failed` and an `error` value:
- `snapshot_failed`: The image couldn't be saved. Try saving the sandbox again.
- `sandbox_stopped`: The sandbox stopped before the image was saved.
Images
Save a sandbox as an image and reuse it to start new sandboxes without reinstalling packages or setting up your
environment again.
An image saves the sandbox's disk, including installed packages, cloned repositories, and files. Every sandbox started
from that image has the same files and dependencies.
The examples use $SANDBOX for a sandbox ID and $IMAGE for an image ID, as described in the
quickstart.
The new sandbox starts with all files from the image and the same CPU and memory settings as the original sandbox. Set
cpu and memory_mb to use a different size.
The new sandbox's image field contains the image ID, and template identifies the template used by the original
sandbox.
You can also save a sandbox created from an image. Each image is independent, so deleting one doesn't affect other
images.
What an image saves
Kept
Not kept
All files on disk, including installed packages and files you created
Network policy and preview ports, which must be configured again
Important: Images include any credentials or tokens saved on disk. Remove sensitive files before saving an image if
you don't want them copied into new sandboxes.
The API lists images in creating, ready, or failed states, newest first. Use state to filter the results.
Deleting an image stops its storage charges immediately. Existing sandboxes created from the image continue running.
Requests for the deleted image return 404.
Pricing
Resource
Price
Stored images
$0.08 per GB-month
Keln bills storage by the hour on the image's size_bytes, starting when the image becomes ready and ending when you
delete it.
For example, a 2.7 GB image costs about $0.22 per month.
Sandboxes created from images use standard sandbox pricing.
Limits
Limit
Default
Error
Images in creating or ready state
20 per workspace
429 image_limit
Images being saved from the same sandbox simultaneously
1
409 snapshot_in_progress
Failed images don't count toward the limit. Delete unused images to make room for new ones.
Errors
Status
Code
When
409
sandbox_not_running
The sandbox is paused or stopped. Resume it first.
409
snapshot_in_progress
An image of this sandbox is still being saved, or you tried to pause the sandbox while saving it.
409
image_not_ready
The image is still creating or has failed.
404
image_not_found
The image doesn't exist in this workspace.
429
image_limit
The workspace has reached its 20-image limit.
Failed images have state: failed and an error value:
snapshot_failed: The image couldn't be saved. Try saving the sandbox again.
sandbox_stopped: The sandbox stopped before the image was saved.