Skip to content

GUIDES · 03

Run a packaged app.

A tebako package is an executable file that carries its own loader. This guide describes the three ways to run a package, which differ only in the amount of control the operator needs over the run.

Note

This guide is part 1 of the Basic payloads tutorial. The blog chapter walks a first run end to end.

A · Direct execution.

Direct execution requires no tebako installation and no setup, because the package carries its own loader. The first run on a machine resolves the runtime, which is downloaded once, verified, cached, and shared by every package that can use it.

$ chmod +x ./metanorma-1.2.3-macos-arm64
$ ./metanorma-1.2.3-macos-arm64 compile site.adoc
resolving runtime: ruby >= 3.3, < 5.0 (macos-arm64)
downloading tebako-runtime-3.3.7 (exe + env image)
verifying sha256
installing (locked)
installed ruby-3.3.7 — cached at ~/.tebako/runtimes/ruby-3.3-3.3.7-macos-arm64

Every later run on that machine prints one line and starts immediately:

runtime ruby-3.3.7 (cached)

The runtime is shared infrastructure rather than part of the package: a second package that accepts the same ruby line reuses the cached copy. The output above is abridged.

B · The tebako run command.

tebako run wraps the same execution with per-run controls. Everything after -- (or the first non-flag token) goes to the payload verbatim; the flags before it shape this run only.

$ tebako run ./myapp -- --help
$ tebako run ./myapp --jail deny -- --help
$ tebako run ./myapp --mount "$HOME/data:/data:ro" -- process /data
$ tebako run ./myapp --no-host -- status

--jail <spec> tightens the filesystem policy for this run. --mount <host:mount:ro|rw> adds a one-off host directory grant, read-only or read-write, and the option is repeated once per grant. --no-host drops every host grant the package requested. The full grammar is in the jails guide.

C · A runtime’s own tools.

A package is not the only thing tebako run starts. When the first token names no existing file, it is read as an engine reference of the form <engine>[:<command>], and the command boots that engine’s runtime directly, with no package in between.

$ tebako run ruby --version
ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [arm64-darwin23]
$ tebako run node:node --version
v24.22.0

The bare form runs the interpreter itself. The colon form runs one of the commands the runtime declares in its own image manifest, and every argument after the reference reaches the command verbatim. The runtime is resolved per engine through the version chain that Shims & versions describes, so the direct surface and the shimmed surface resolve identically.

The declared command sets differ by engine and platform, because each factory publishes the surface its distribution actually carries:

Engine Declared commands

Notes

Java (Temurin)

java, jfr, jrunscript, jwebserver, keytool, rmiregistry

The complete bin inventory of the staged JRE.

Java (GraalVM)

java, jar, jarsigner, javac, javadoc, javap, jcmd, jconsole, jdb, jdeps, jfr, jimage, jinfo, jlink, jmap, jmod, jpackage, jps, jrunscript, jshell, jstack, jstat, jwebserver, keytool, rmiregistry, serialver, native-image, native-image-configure, native-image-utils

The JDK tool set; the native-image tools are Windows .cmd launchers and are not declared there.

Node.js

node, npm, npx, corepack

npm, npx, and corepack are not declared on Windows.

Bun

bun, bunx

TruffleRuby

ruby, gem, bundle, bundler, irb, rake, rdoc, ri, rbs, rdbg, racc, erb, syntax_suggest, truffleruby, truffleruby-polyglot-get

JRuby

jruby, jgem, jirb

The commands run on the Java runtime the JRuby image composes with.

Python

pip, pip3

Declared from the v0.3.1 line onward, generated from the installed pip’s own console-script metadata on every platform.

Ruby (MRI)

gem, irb, rake, bundle, bundler, rdoc, ri, rdbg, rbs, racc, erb, syntax_suggest, typeprof, minitest, test-unit

A command that the runtime does not declare is refused by name, never silently rerouted:

$ tebako run node:nosuch
tebako-runtime-launcher: --tebako-entry 'nosuch': the env image declares no
runtime entrypoint of that name — the parent's expose list outruns the
runtime's spawn surface

tebako install <engine>[:<command>] registers the same reference as a command on PATH, which the Shims & versions guide covers.

D · The managed way: registry, install, shim.

For a tool in daily use, the managed flow applies: a registry resolves names and versions, an explicit install places the payload into the store, and a shim on PATH exposes the payload as an ordinary command.

$ tebako add-registry tfs:github:tebako-packages/metanorma
$ tebako install metanorma
installed metanorma 1.2.3 -> ~/.tebako/payloads/metanorma/1.2.3.tfs
shim ~/.tebako/shims/metanorma
$ tebako-shim install-shell    # once per machine
$ metanorma compile site.adoc

The shim selects the payload version and a compatible runtime for every invocation; env overrides, project pins, and defaults are covered in Shims & versions. Output versions shown are representative.

Two rules worth knowing.

  • Offline is a mode. With TEBAKO_OFFLINE=1, a run is a cache hit or a named error (exit 69), never an unannounced fetch.

  • A run never installs. Executing a package resolves the shared runtime, but nothing from the package’s payload enters the store. Installation is the explicit verb: tebako install.

See also: Install tebako · Set a jail policy · The store, in the architecture docs.