https://github.com/do-2k24-27/rusty-initramfs-builder

A Rusty CLI tool to convert Docker/OCI images into bootable initramfs for microVMs.
https://github.com/do-2k24-27/rusty-initramfs-builder

initramfs lambda microvms serverless

Last synced: about 1 month ago
JSON representation

A Rusty CLI tool to convert Docker/OCI images into bootable initramfs for microVMs.

• Host: GitHub
• URL: https://github.com/do-2k24-27/rusty-initramfs-builder
• Owner: DO-2K24-27
• License: mit
• Created: 2026-01-28T17:06:42.000Z (4 months ago)
• Default Branch: main
• Last Pushed: 2026-03-12T17:01:16.000Z (3 months ago)
• Last Synced: 2026-03-12T23:00:03.245Z (3 months ago)
• Topics: initramfs, lambda, microvms, serverless
• Language: Rust
• Homepage: https://crates.io/crates/initramfs-builder
• Size: 1.44 MB
• Stars: 5
• Watchers: 0
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


rusty-initramfs-builder

A Rusty CLI tool to convert Docker/OCI images into bootable initramfs for microVMs 🦀


![builder](./docs/builder.png)



  ![Stars](https://img.shields.io/github/stars/DO-2K24-27/rusty-initramfs-builder?logo=github) ![Downloads](https://img.shields.io/crates/d/initramfs-builder?logo=rust)[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![GitHub release](https://img.shields.io/github/v/release/DO-2K24-27/rusty-initramfs-builder?color=success)](https://github.com/DO-2K24-27/rusty-initramfs-builder/releases/latest)

  



## Installation

```bash

cargo install initramfs-builder

```

## Quick Start

```bash

# Build an initramfs from a Docker image

initramfs-builder build python:3.12-alpine -o python.cpio.gz

# Inject a custom binary and init script

initramfs-builder build python:3.12-alpine \

  --inject ./my-agent:/usr/bin/my-agent \

  --init ./init.sh \

  -o python-lambda.cpio.gz

```

## Usage

```bash

# Build initramfs

initramfs-builder build  [OPTIONS]

Options:

  -o, --output        Output file [default: initramfs.cpio.gz]

  --inject        Inject file into initramfs (can be repeated)

  --init            Custom init script (placed at /init)

  --exclude <PATTERN>       Exclude files matching pattern

  --platform-arch <ARCH>    Target architecture [default: amd64]

  -c, --compression <FMT>   gzip, zstd, or none [default: gzip]

# Inspect image

initramfs-builder inspect <IMAGE>

# List layers

initramfs-builder list-layers <IMAGE>

```

## Example init script

```bash

#!/bin/sh

mount -t proc proc /proc

mount -t sysfs sysfs /sys

mount -t devtmpfs devtmpfs /dev

exec /usr/bin/my-agent

```

## Documentation

See [docs/](docs/) for detailed documentation:

- [Architecture](docs/architecture.md) - How it works internally

- [Integration](docs/integration.md) - Using with rust-vmm/Firecracker

## License

MIT