YAOSHI · 曜匙

v0.0.1 | --:--:-- UTC | 01 — 05

Installer Image Workbench

YAOSHI

曜匙

Create a complete USB-writable Yaoshi Debian installer image

Build · Ready Verify · QEMU Emit · 1 Image

Scroll · 5 Frames

02 / Mission · Singular Purpose

SCOPE · LOCKED | 02 — 05

02 · Mission

A small, strict workbench that builds and verifies USB-writable Debian installer images — nothing more, nothing less.

001 · Build A Debian 13 trixie installer image, embedded with a TargetDiskImage payload.

002 · Verify A QEMU functional check from boot, to install, to post-boot Console readiness.

003 · Isolate All product state stays inside ./.yaoshi/ within the current working directory.

Not a: general OS builder fleet manager release platform policy engine service catalog multi-tenant platform

03 / Surface · Four Commands

EXIT · 0 / 2 / 3 / 4 / 5 / 6 / 7 | 03 — 05

03 · Surface

Four commands. One workspace. One image.

01 · INIT ~ 40ms

init

Create an annotated sample configuration in the current workspace.

→ Initialized: ./.yaoshi/yaoshi.toml

02 · BUILD ~ 4m20s

build

Assemble a USB-writable Debian installer image, end to end.

→ Built: ./.yaoshi/images/yaoshi-*.img

03 · CHECK ~ 2m05s

check

Functionally check the installer image inside a QEMU sandbox.

→ Checked: ./.yaoshi/check/report.md

04 · CLEAN ~ 80ms

clean

Remove cache, logs, images, or check artifacts — selectively or all.

→ Cleaned: cache · logs · images · check · all

workspace · zsh · 80×24 PID 4017 · TTY pts/0

$cargo run -p yaoshi --
                                    init
Initialized: ./.yaoshi/yaoshi.toml
$cargo run -p yaoshi --
                                    build
… assembling rootfs · generating UKI · packing flash image …
Built: ./.yaoshi/images/yaoshi-20260515-070504.img
                            
$cargo run -p yaoshi --
                                    check
… booting installer in QEMU · observing install · verifying post-boot
                                …
Checked: ./.yaoshi/check/report.md  [ Status: passed ]
$

03 / Surface · Commands

03 — 07

03 · Surface

Four commands. One workspace. One image.

01 · INIT ~ 40ms

init

Create an annotated sample configuration.

→ Initialized: ./.yaoshi/yaoshi.toml

02 · BUILD ~ 4m

build

Assemble a USB-writable installer image, end to end.

→ Built: ./.yaoshi/images/yaoshi-*.img

03 · CHECK ~ 2m

check

Functional check inside a QEMU sandbox.

→ Checked: ./.yaoshi/check/report.md

04 · CLEAN ~ 80ms

clean

Remove cache, logs, images, or check artifacts.

→ Cleaned: cache · logs · images · check

04 / Surface · Console

04 — 07

03 · Surface · Live

End-to-end. Quietly.

Exit · 0ok 2config 3build 4check 5io 6lock 7cancel

workspace · zsh

$ cargo run -p yaoshi --
                                    init
Initialized: ./.yaoshi/yaoshi.toml
$ cargo run -p yaoshi --
                                    build
… assembling rootfs · packing flash image …
Built: ./.yaoshi/images/yaoshi-*.img
$ cargo run -p yaoshi --
                                    check
… booting in QEMU · verifying post-boot …
Checked: report.md [passed]
$

04 / Image · Architecture

ROOTLESS · NO LOOP / MOUNT / CHROOT | 04 — 05

04 · Image Architecture

A FlashImage that boots, carries, and writes a TargetDiskImage — byte for byte.

FlashImage USB Boot Container GPT · 2 part · ~3.8 GiB

P1 · YAOSHI-FLASH-ESP 256 MiB · fat32

UEFI boot files + installer UKI

P2 · YAOSHI-PAYLOAD ~3.5 GiB · raw

Payload Header + TargetDiskImage (uncompressed, embedded)

embeds & writes

TargetDiskImage Written to Target Disk GPT · 2 part · ext4

P1 · YAOSHI-SYSTEM-ESP 512 MiB · fat32

Post-install boot files

P2 · YAOSHI-ROOT ~3.0 GiB · ext4

ext4 root filesystem · root-only model

load-config

toolchain

bootstrap-rootfs

assemble-archive

select-kernel

generate-initrd

build-uki

make-target-disk

pack-flash · emit

LangRust 1.95.0/ Bootsystemd-boot · UKI/ Rootfsmmdebstrap → virt-make-fs/ UIRatatui · Askama/ VerifyQEMU · cargo-nextest/ EnvNix flake · direnv

05 / Image · Architecture

05 — 07

04 · Image Architecture

A FlashImage that boots, carries, and writes a TargetDiskImage — byte for byte.

FlashImage USB Boot Container ~3.8 GiB

P1 · FLASH-ESP 256 MiB

UEFI boot files + installer UKI

P2 · PAYLOAD ~3.5 GiB

Payload Header + TargetDiskImage embedded

embeds & writes

TargetDiskImage Written to Target Disk ext4 root

P1 · SYSTEM-ESP 512 MiB

Post-install boot files

P2 · ROOT ~3.0 GiB

ext4 root filesystem · root-only

06 / Image · Pipeline

06 — 07

04 · Build Pipeline

Nine stages. Reproducible.

load-config

toolchain

bootstrap-rootfs

assemble-archive

select-kernel

generate-initrd

build-uki

make-target-disk

pack-flash · emit

LangRust 1.95/ Bootsystemd-boot · UKI/ Rootfsmmdebstrap/ UIRatatui · Askama/ VerifyQEMU · nextest/ EnvNix · direnv

05 / Workspace · Source

END · OF · SEQUENCE | 05 — 05

05 · Workspace

Everything lives in ./.yaoshi/

./.yaoshi/
├── yaoshi.toml          1.2K  // only user config
├── images/
│   └── yaoshi-*.img     ~3.7G // USB-writable image
├── cache/
│   └── v1/               var   // content-addressed
├── check/
│   ├── report.md        ~4K   // functional check
│   ├── serial.log       ~60K  // QEMU serial
│   ├── known_hosts
│   └── run-UTC-*/
├── logs/
│   └── run-UTC-*/         var   // per-run logs
└── lock                  0B    // workspace lock

Manifesto

"Yaoshi is a small, strict Debian installer workbench — build, cache, and check inside your current directory, and emit one image you can write to USB."

github.com/eggybyte-technology/yaoshi →

07 / Source · Workspace

07 — 07

05 · Workspace

Everything lives in ./.yaoshi/

./.yaoshi/
├── yaoshi.toml      1.2K
├── images/
│   └── yaoshi-*.img ~3.7G
├── cache/
│   └── v1/           var
├── check/
│   ├── report.md    ~4K
│   ├── serial.log   ~60K
│   └── run-UTC-*/
├── logs/
│   └── run-UTC-*/     var
└── lock              0B

Manifesto

"Yaoshi is a small, strict Debian installer workbench — build, cache, and check inside your current directory, and emit one image you can write to USB."

github.com/eggybyte-technology/yaoshi →