Skip to content

ARCHITECTURE · STORE

The store: one directory, nothing hidden.

Everything tebako keeps on your machine lives under one roof — ~/.tebako. Runtimes download once and are shared by every application; payloads stay byte-identical with what the publisher released; uninstalling means deleting files. There is no daemon, no database, no state anywhere else.

SHIPPEDshipped in v2.0.0 — inspect yours with tebako info store

The layout.

Precious things (your config, your trust pins, your keys) sit next to re-derivable things (runtimes, payloads, registry caches) — so a backup policy and a cleanup policy are both obvious. Every downloaded artifact carries its own trust anchor beside it.

~/.tebako — override with TEBAKO_HOMEruntimes/ruby-3.3-3.3.7-macos-arm64/├── tebako-runtime-…-macos-arm64 0755├── tebako-runtime-…-macos-arm64.tfs 0444 · the env image├── <image>.sha256 ◀ the trust anchor└── <image>.origin — where it came frompayloads/metanorma/├── 1.2.3.tfs 0444 — byte-identical with the release├── 1.2.3.tfs.sha256 ◀ verified at install, never per run└── 1.2.3.manifest.yaml — the manifest, mirrored outshims/├── metanorma → link to the dispatcher; this dir on PATH└── .disabled.yaml — tools you parkedregistries/└── <sha>.yaml (+ .fetched-at) — dispatch cache, 24 h TTLconfig.yamlyour defaults · your registries · runtime preferenceskeys/  trust/your signing keys · pinned publisher keysjournal.log  locks/  tmp/THE HOUSE RULESA run is a run.Executing a package never installsits slices. tebako install is the verb.Atomic installs.Downloads land in tmp/ and renameinto place — a partial install isinvisible, never half-used.One writer at a time.Per-entry file locks, 120 s timeout,a stale lock names itself.Verify once, run forever.The .sha256 sidecar means "verifiedat install". Runs never re-verify —that is what makes them fast.Read-only artifacts.Payloads and images are 0444. Samename+version with different bytes isrefused loudly, never overwritten.Offline is a mode.TEBAKO_OFFLINE=1 — cache hit, or anamed error. Never a surprise fetch.

Install and run are different verbs.

Double-clicking a package, or executing it in a terminal, runsit: the loader resolves the runtime (downloading it once if needed — that is runtime resolution, shared infrastructure, not installation) and starts your program. Nothing from the package's payload slots enters the store.

tebako install is the explicit verb: it brings a payload into the store — downloaded to a temporary location, verified against its published SHA-256, renamed into place read-only — and registers a shim for every command the payload declares. Registry installs always register shims; installing a local package file registers them only when you pass --shims. tebako uninstall removes the shims and the cache entry.

The store itself is versioned: a single integer marks its layout generation. A newer store refuses an older tool with a named error instead of a silent mix, and an older store is migrated by name, never silently rewritten.

Housekeeping.

The cache is yours to inspect and prune. Everything here is read-only against the store; nothing fetches.

See what is cached

tebako cache list
tebako info store      # disk usage by section
tebako info runtimes   # with --remote: what the factory offers

Reclaim space

tebako cache prune --older-than 90d
tebako cache prune --all

Pruning only ever removes re-derivable artifacts — the next run that needs one downloads and verifies it again. Your config, keys, and trust pins are never pruned.

Why a directory and not a database.

Because the tree is the truth. Every artifact carries its own proof (the sidecar), its own provenance (the origin marker), and its own manifest mirror — so the store is auditable with ordinary tools, repairable by deleting things, and portable by copying it. The registry caches are the only derived state, and they rebuild themselves on a 24-hour cycle or on tebako update-registries.