How a Tebako package works.

A tebako package is a composition of independently distributable parts. Each part has its own release line, its own publisher, and its own trust anchor; the executable you download is where they meet.

The package file is the bootstrap followed by payload slots, a slot table, optional extension blocks, and a 166-byte trailer header at the very end — read last, first. A fat package carries its runtime in a slot and never touches the network; a lean package references the runtime and resolves it at run time.

Figure 1 — Byte layout of a tebako package: bootstrap, payload slots, slot table, extension blocks, and the trailer header at end of file.

Runtimes are factory products, not local builds. An official Ruby release flows through two factories before any user machine sees it, and every boundary is a published, checksummed release — each stage consumes the previous stage’s artifacts, never its source tree. The full stage-by-stage table is on the factories page.

Figure 2 — The release chain: ruby-lang.org tarball through the source and runtime factories to the product and the user machine, with the seven platform triplets.

There are two front doors and one mechanism behind them. Standalone: you execute a package file directly — the bootstrap inside reads its own trailer and resolves the runtime. Managed: you invoke a command name on PATH — a shim link to the dispatcher, which picks the payload version and the runtime per invocation. Either way, the same handoff happens at the end: the runtime executable starts with a list of images to mount and an entrypoint to run.

Figure 3 — The dispatch sequence: invocation name, version chain, runtime resolution, the exec handoff, and the driver mounting images before the entrypoint runs.

Two consequences worth internalizing. First, a run is a run: executing a package never installs its slices — installation is the explicit verb, tebako install. Second, verification happens at fetch and install, never per run — a cached, verified artifact starts at full speed every time.

Inside the running process there is one virtual filesystem. The env image mounts whole at the runtime root — the path the interpreter was compiled to live at — and every payload mounts at the path its consumer declared. A path lookup resolves against the longest matching mount prefix; mounts may nest; and the host filesystem is visible only where the jail allows it. Payload images are always read-only.

Figure 4 — The mount model: the env image at the runtime root, payloads at consumer-declared mounts, and longest-prefix dispatch.

The consumer-declared mount is the dependency mechanism: an application’s manifest says I need inkscape, this version range, at `/opt/inkscape` — the slice itself stays location-agnostic, and one installed copy serves every application that mounts it. The worked example on the audience page runs this end to end; the manifest grammar is on the feature surface.

The loader and the runtime are separate artifacts with separate release lines, so they can drift apart. Tebako’s answer is a declared handoff contract: every runtime release states which handoff semantics it speaks, and the loader checks the declaration before downloading, before mounting, before running anything. A combination that cannot work is refused by name — the error tells you both generations and the remedy — instead of failing later as a corrupted environment or a segfault.

The same rule covers packages and payloads: every artifact belongs to a declared generation, and anything that predates declarations is treated as the oldest one and refused by name when it no longer fits. The failure you meet in practice is a sentence like "this package was pressed by a newer tebako — upgrade your CLI" or "this runtime is too old for this package — pin an older payload or upgrade the runtime": a named error with an exit code, never a silent fallback and never a half-installed cache.

The loader and the runtime’s mount driver share a small, stable set of refusal codes. Scripts can branch on them; humans get a one-line message that says what was refused and why.

Once the interpreter is running, its own exit codes are the program’s — the loader is out of the picture by then.

See also: Where everything lives · The chain of trust · Running binaries from images.