GUIDES · 02

The first ten minutes.

What a machine that has never seen tebako can do in about ten minutes, measured rather than described: install, run a payload, run one that carries its own language runtime, and press a package of your own.

Note	Every number on this page comes from one run of `tools/stranger-walkthrough.sh` against a published release, in an empty `HOME`, with the release assets downloaded exactly as they are published. Re-running the script is how the page is updated; nothing here is recalled from memory.

The five binaries.

The release publishes one asset per binary per platform, and the asset names carry the version while the binaries expect the bare names. Rename on download — skipping this stops tebako install at the shim step, after it has already downloaded the payload:

$ mkdir -p ~/.local/bin && cd ~/.local/bin
$ for b in tebako tebako-pkg tfs tebako-bootstrap tebako-shim; do
    curl -fsSLO "https://github.com/tamatebako/tebako/releases/download/v<ver>/$b-<ver>-macos-arm64"
    mv "$b-<ver>-macos-arm64" "$b"
  done
$ chmod 0755 tebako tebako-pkg tfs tebako-bootstrap tebako-shim
$ ./tebako --version
Tebako executable packager version <ver>

tebako-shim is the fifth binary and the one a hand download forgets: it is the dispatcher every installed shim links to. Homebrew and the shell installer put all five in place, with their names, for you.

A first payload.

tebako setup seeds the official registry. There is nothing to add for the first command, and adding a second registry that carries the same payload name turns a bare install into an ambiguity error — the message names both registries and asks for the full reference.

$ tebako setup
fetching registry tfs:github:tebako-packages/registry
seeded the official registry tfs:github:tebako-packages/registry (16 payload(s))
$ tebako install hello
resolving hello
└ toolkit hello 2.12 — fetching
fetching payload hello@2.12: 1 artifacts, unknown total
downloading payload hello@2.12 (28.3 KB)
installed payload hello@2.12 (28.3 KB)
fetched payload hello@2.12: 1 artifacts, unknown in 2.7s
1 node(s): 0 cached, 1 fetched, 0 skipped
installed hello 2.12 -> ~/.tebako/payloads/hello/2.12.tfs
  signature verified (signer 7a437d7382a3cf5a)
  shim ~/.tebako/shims/hello
$ tebako-shim install-shell    # once per machine
installed the tebako shim block in ~/.bashrc (bash)
restart the shell, or re-source the file
$ hello
Hello, world!

Open a new shell after install-shell, or call the shim by path (~/.tebako/shims/hello) until you do: it writes the PATH line into your shell’s startup file, which the current shell has already read.

A payload that carries a runtime.

A payload of kind runtime provides an interpreter, and the payloads that need one declare it as a dependency. The first run fetches the runtime — once per machine — verifies it, and caches it; every later run starts from the cache.

$ hello-ruby
fetching registry tfs:github:tamatebako/tebako-runtime-ruby
fetching runtime ruby@4.0.7;tebako=0.17.3;image: 2 artifacts, 19.2 MB total
downloading tebako-runtime-0.17.3-ruby-4.0.7-macos-arm64.tfs
runtime env image tebako-runtime-0.17.3-ruby-4.0.7-macos-arm64.tfs (19.2 MB) — lazy: seeding on demand, sealing in background
downloading tebako-runtime-0.17.3-ruby-4.0.7-macos-arm64 (46.3 MB)
installed tebako-runtime-0.17.3-ruby-4.0.7-macos-arm64 (46.3 MB)
fetched runtime ruby@4.0.7;tebako=0.17.3;image: 2 artifacts, 19.2 MB in 1.9s
Hello from tebako (ruby 4.0.7, arm64-darwin23)

The store keeps the runtime under ~/.tebako/runtimes and never extracts it into a system path; tebako doctor names anything that has drifted, with its remedy.

Press your own.

A directory with one root script is a project. tebako press detects it, resolves the runtime from the registry — the same pair install would pick — and writes a single executable that carries your code and mounts it.

$ mkdir hello && cd hello
$ echo 'puts "hello from a pressed app (ruby #{RUBY_VERSION})"' > main.rb
$ tebako press -r . -e main.rb -o ../hello.bin
   Ruby version:             '4.0.7'
Created tebako package at "…/hello.bin"
$ ../hello.bin
hello from a pressed app (ruby 4.0.7)

Write the package outside the project root. Pressing in place works — the tool says so, then warns — because each press would image the previous package sitting beside the source, which is how old versions end up nested inside new ones.

Press it again after an edit: the packaging environment is reused, so the loop is a few seconds rather than a download.

What the numbers were.

A single run of the walkthrough script, on the release named in its header, in an empty HOME:

step	seconds	exit
`tebako setup`	1.74	0
`tebako install hello`	3.72	0
`tebako-shim install-shell`	0.26	0
`hello`	0.16	0
`tebako install hello-ruby`	4.14	0
`hello-ruby (first run)`	6.60	0
`tebako press (cold)`	4.66	0
`tebako press (again)`	4.05	0
`the pressed app`	0.94	0

$ tools/stranger-walkthrough.sh --version <ver>

The script times each step, exits non-zero if any step fails, and prints the store’s shape afterwards so the page can state what landed as well as how long it took.

Where to go next.

The install guide covers Homebrew, the shell installer and the direct binaries, and what each one lands.
The run guide covers tebako run, shims and version pinning.
The package guide covers lean versus fat packages, extra slices, and the jail policy a package can declare.