Skip to content

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.

Save a sandbox as an image

Set up your sandbox, then save it as an image:

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:

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 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

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.