What is tebako?

The platform is a single design, and that design is generic across four axes. Nothing in the loader, the container, or the store is shaped around Ruby; Ruby happens to be the first runtime that the factories produce.

Everything tebako does decomposes into six verbs.

Everything in the platform orbits one seam: the tebako_fs_* C ABI, implemented by the Rust tfs crate. The factories feed runtimes to this seam, and feedstock repositories, one per package, build payloads on those runtimes and host them on their own releases; the factories walk that chain. The trust layer sits beneath everything that moves bytes.

Figure 1 — Platform map: the TFS core, the factories and the product line around it, the trust layer beneath.

The gem-era orchestrator is retired: the C++/gem codebase is archived at tamatebako/tebako-v1 and the product is the Rust workspace at tamatebako/tebako.

A tebako package is a composition of up to three independently distributable parts, glued by the tpkg trailer: a 166-byte header at end of file plus 280-byte slot records. The format version is 1 forever: extensions live in flags (LEAN, SIGNED_V2, NO_INSTALL) rather than in version bumps, so v1 readers parse v2 packages untouched. The full byte tables live in concepts.

Figure 2 — Anatomy of a tebako package: bootstrap, optional runtime slot (fat packages), one to eight payload slots, optional v2 signature extension, and the tpkg trailer header at end of file.

A · the bootstrap — the Rust loader, a static binary under 3 MB. It is the process entry point of every stitched package: it reads its own trailer, resolves the runtime, verifies it, and hands off.

B · the runtime — two artifacts rather than one: the interpreter executable and the env image (a .tfs carrying the runtime’s files). They are downloaded once into the shared cache, sha256-verified, and mounted — never extracted. Fat packages carry the runtime as a slot; lean packages carry a reference and fetch on first run.

C · the payload slices — bare .tfs images, self-describing through an in-image manifest (/tpkg/manifest.yaml). The container’s format_id answers exactly one question, how to read the bytes (limnifs, dwarfs-t, squashfs, zip); whether a slot is a runtime, and which payload carries the entrypoint, are manifest semantics that are never encoded in the format axis. LimniFS is the default image format as of tebako v0.2.0, and dwarfs-t remains a first-class read backend.

The engine is the same, and the two modes differ in the relationship between the developer and the user: the developer hands over one file and disappears, or the developer publishes versioned payloads that a dispatcher assembles per invocation.

Figure 3 — Standalone mode versus managed mode, side by side.

TFS is a product in its own right: a userland virtual filesystem with a mount table, longest-prefix dispatch, pluggable read-only backends, and copy-on-write and encryption transforms above them. The Rust tfs crate is the shipping implementation of the tebako_fs_* C ABI (33 exports), and it drives every mount on this page. The C++ libtfs survives as the legacy parity oracle, and the Rust ABI runs its contract suite byte-for-byte.

Figure 6 — The TFS router: longest-prefix dispatch onto read-only backends, with a copy-on-write overlay above and pass-through to the host outside every mount.

Any project, in any language, can attach images to its binaries through the same ABI, or it can drive images from the shell with the tfs CLI. dwarfs-t, the only C++ in the ecosystem, and dwarfs-t-rs, its standalone Rust binding, are consumable without any knowledge of tebako. Every backend is read-only at runtime forever; writing exists only as the copy-on-write overlay plus a creation-time writer. The the VFS model page presents the full model.

One signature mechanism, OpenPGP via rnp-rs, runs from the publisher’s key to the user’s run. Signing is opt-in per package, and verification of anything signed is always strict. Verification happens at install and never per run; failures are named exits, never crashes. Details appear on the the chain of trust page.

Figure 7 — The tebako chain of trust: root key, release keys, per-artifact SHA256 digests, and the tpkg v2 signature verified at install.

The audience rule is stated once: prebuilt artifacts flow downward, and compilation never flows outward. Only the people building tebako itself ever compile tebako.

The four audiences meet the platform matrix at different depths, and the windows-arm64 triplet is the one place where that depth differs per audience.

One toolchain note applies to Windows as a whole. The shipped binaries are compiled with GCC under MSYS2 ucrt64 on x64 and with clang and libc++ under MSYS2 clangarm64 on arm64, because MSYS2 publishes no GCC for aarch64 windows. An MSVC build of tebako is not shipped on either architecture; MSVC appears in the pipeline only as the host compiler for build-time helpers.

See also: concepts · the factories · the VFS model · runtime as image · dispatch · the store · the chain of trust · the repo map · for contributors.