Skip to content

UNDER THE LID

How the box works.

A tebako package is not one blob — it is a composition of up to three independently distributable parts, glued by a trailer at the end of the file. Beneath the poetry is a loader, a runtime, and payload images.

New to tebako? Start with the platform overview: What is Tebako? →

The three parts.

Every package combines a loader, a runtime, and one or more payload slices. Each part ships on its own release line; the tpkg trailer at the end of the file records which slices are carried inside and where they mount.

A · BOOTSTRAPThe Rust loader< 3 MB, size-gated in CIreads its own trailerresolves the runtime, hands offthe process entry pointB · RUNTIME — TWO ARTIFACTSInterpreter exe + env imagetebako-runtime-…-[exe]tebako-runtime-…-.tfsdownloaded once per machinemounted whole, never extractedC · PAYLOAD SLICESBare .tfs imagesapp · data · fonts · native tools/__tpkg__/manifest.yaml insideself-describing, versioned, signedco-mounted in one processtpkg trailer — 166-byte header + 280-byte slot records, format version 1, at end of file

What a run looks like.

Whether the user runs a stitched package directly or through a shim on PATH, the same handoff happens: the bootstrap resolves the runtime, the driver inside the runtime mounts the images, and the entrypoint starts.

$ ./my-app — or a shim on PATHuser runs the package1Bootstrap reads its trailerSlots, mount points, the runtime reference — parsed, never guessednamed errors, named exit codes — no silent fallbacks2Runtime resolvesCache hit in ~/.tebako — or download once, sha256-verifiedverified at install, never per run3Handoff to the runtime exe--tebako-image per payload · TEBAKO_RUNTIME_IMAGE · --tebako-entrythe launcher ABI, version 14Driver mounts the imagesEnv image at the runtime root, payloads at declared mounts, jail lastduplicate mount → EEXIST · any failure → no partial mountThe entrypoint runs — argv rewritten into the VFS

What's inside the file.

A package is a concatenation, not a nesting doll: the loader's bytes, then each payload image as a slot, then the trailer at the very end. A lean package carries no runtime slot — the trailer names what to resolve instead.

my-appELF / Mach-O / PEbootstrap< 3 MBslot 0 · payload imagelimnifs by defaultmanifest inside the imagemore slots as declaredslot 1runtime(fat only)traileroffset 0EOF — the trailer always reads from the tailslots carry offset · size · format · mount point

Bootstrap

The Rust loader — the process entry point of every stitched package. Reads the trailer, resolves the runtime, hands off.

Payload slots

Bare .tfs images — your app, its data, its native tools. Self-describing via an in-image manifest; limnifs is the default image format.

Runtime slot (fat only)

In a fat package the runtime travels inside. In a lean one, the trailer's runtime reference resolves it from the shared cache instead.

tpkg trailer

A 166-byte header plus one 280-byte record per slot, at end of file. Format version 1 forever — extensions live in flag bits, never in version bumps.

PACKAGING MODES

Two ways to press.

Lean

The default. A small package: bootstrap plus payload slices. The runtime resolves from the shared cache — or downloads once, verified, on first run.

Fat

The runtime travels inside the package as a slot. One file, nothing to resolve — at the price of carrying the world.

The product is Rust.

The loader, the CLI, the virtual filesystem, and the trailer tooling are all Rust, shipped as prebuilt binaries — nothing of tebako compiles on your machine. The only C++ left is the dwarfs-t image library behind the reader ABI, and imaging runs in-process: no shell-outs, no system dependencies. The v1 gem-and-C++ era is archived attebako-v1.

What is Tebako? The platform overview →Where the artifacts come from →
View the source