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

# ImageSource

> ImageSource reference: define metadata for downloadable Celesto kernel and rootfs images, including URLs, file names, and SHA-256 verification hashes.

`ImageSource` defines the metadata for a downloadable VM image, including URLs and SHA-256 checksums for verification.

## ImageSource

### Attributes

**name** `str` *required*

Human-readable image name used for caching and identification.

**kernel\_url** `str` *required*

URL to download the kernel binary.

**kernel\_sha256** `str | None` (default: None)

Expected SHA-256 hex digest of the kernel. If `None`, checksum verification is skipped for the kernel.

**rootfs\_url** `str` *required*

URL to download the root filesystem image.

**rootfs\_sha256** `str | None` (default: None)

Expected SHA-256 hex digest of the rootfs. If `None`, checksum verification is skipped for the rootfs.

### Usage

```python theme={null} theme={null}
from celesto import ImageSource

# Define an image with checksum verification
image = ImageSource(
    name="ubuntu-jammy",
    kernel_url="https://example.com/kernels/jammy-vmlinux.bin",
    kernel_sha256="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    rootfs_url="https://example.com/rootfs/jammy-rootfs.ext4",
    rootfs_sha256="cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce",
)

print(image.name)  # ubuntu-jammy
print(image.kernel_url)
```

### Without Checksum Verification

You can skip SHA-256 verification by omitting the checksum fields:

```python theme={null} theme={null}
from celesto import ImageSource

# No checksum verification
image = ImageSource(
    name="test-image",
    kernel_url="https://example.com/vmlinux.bin",
    rootfs_url="https://example.com/rootfs.ext4",
)
```

> [!WARNING]
>
> Skipping checksum verification is not recommended for production use. Always verify image integrity when possible.

### Custom Registry

Use `ImageSource` to define custom images for `ImageManager`:

```python theme={null} theme={null}
from celesto import ImageManager, ImageSource

custom_images = {
    "alpine-minimal": ImageSource(
        name="alpine-minimal",
        kernel_url="https://cdn.example.com/alpine-vmlinux.bin",
        kernel_sha256="abc123...",
        rootfs_url="https://cdn.example.com/alpine-rootfs.ext4",
        rootfs_sha256="def456...",
    ),
    "debian-dev": ImageSource(
        name="debian-dev",
        kernel_url="https://cdn.example.com/debian-vmlinux.bin",
        rootfs_url="https://cdn.example.com/debian-rootfs.ext4",
    ),
}

manager = ImageManager(registry=custom_images)
image = manager.ensure_image("alpine-minimal")
```

## LocalImage

`LocalImage` represents a VM image that has been downloaded and cached locally.

### Attributes

**name** `str` *required*

Image name.

**kernel\_path** `Path` *required*

Absolute path to the kernel binary on the local filesystem.

**rootfs\_path** `Path` *required*

Absolute path to the root filesystem on the local filesystem.

### Usage

```python theme={null} theme={null}
from celesto import ImageManager, VMConfig, Celesto

manager = ImageManager()
image = manager.ensure_image("hello")

print(type(image))  # <class 'celesto.images.manager.LocalImage'>
print(image.name)   # hello
print(image.kernel_path)  # PosixPath('/home/user/.celesto/images/hello/vmlinux.bin')
print(image.rootfs_path)  # PosixPath('/home/user/.celesto/images/hello/rootfs.ext4')

# Use with VMConfig
config = VMConfig(
    kernel_path=image.kernel_path,
    rootfs_path=image.rootfs_path,
)

with Celesto(config) as vm:
    vm.start()
```

### Immutability

Both `ImageSource` and `LocalImage` are immutable (frozen) Pydantic models:

```python theme={null} theme={null}
from celesto import ImageSource

image = ImageSource(
    name="test",
    kernel_url="https://example.com/vmlinux.bin",
    rootfs_url="https://example.com/rootfs.ext4",
)

# This will raise an error
try:
    image.name = "modified"
except Exception as e:
    print(f"Error: {type(e).__name__}")  # Error: ValidationError
```

## SHA-256 Checksum Generation

To generate SHA-256 checksums for your images:

```bash theme={null} theme={null}
# Linux/macOS
sha256sum vmlinux.bin
sha256sum rootfs.ext4

# Or using Python
python3 -c "import hashlib; print(hashlib.sha256(open('vmlinux.bin', 'rb').read()).hexdigest())"
```

## Built-in Images

Celesto includes these built-in `ImageSource` definitions:

```python theme={null} theme={null}
from celesto.images.manager import BUILTIN_IMAGES

for name, source in BUILTIN_IMAGES.items():
    print(f"{name}:")
    print(f"  Kernel: {source.kernel_url}")
    print(f"  Rootfs: {source.rootfs_url}")
    print(f"  Verified: {source.kernel_sha256 is not None}")
```

## Related

* [ImageManager](https://celesto.ai/docs/celesto/api/imagemanager.md) - Download and cache images
* [ImageBuilder](https://celesto.ai/docs/celesto/api/imagebuilder.md) - Build custom images with SSH
* [VMConfig](https://celesto.ai/docs/celesto/api/vmconfig.md) - Configure VM instances


## Related topics

- [ImageManager](https://celesto.ai/docs/celesto/api/imagemanager.md)
- [ImageBuilder](https://celesto.ai/docs/celesto/api/imagebuilder.md)
- [Published images](https://celesto.ai/docs/celesto/concepts/published-images.md)
- [celesto image](https://celesto.ai/docs/celesto/cli/image.md)
- [Custom Sandbox Images with Docker](https://celesto.ai/docs/celesto/guides/custom-images.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.