A small, honest tarball installer

Instead of asking people to extract a .tar.xz somewhere and run a random binary by hand, Tarminal installs the app into a standard location, creates a command, a desktop menu entry and an icon, tracks what it installed, and removes it cleanly later.

The project is split into two Cargo packages: tar-install, a reusable library, and tarminal, the CLI frontend built on top of it. If someone runs the bare tar-install binary directly, it just points them at tarminal.

Written in Rust, MIT licensed, maintained by TamKungZ_. The reusable core is published as the tar-install Rust crate and Python bindings for tools that want to build on the installer directly.

Tarminal installing an application from a plain tarball.

Install Tarminal

curl -fsSL https://packages.tamkungz.me/gpg.key | \
  sudo gpg --dearmor -o /usr/share/keyrings/tamkungz-packages.gpg

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/tamkungz-packages.gpg] https://packages.tamkungz.me/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/tamkungz-packages.list

sudo apt update
sudo apt install tarminal

sudo add-apt-repository ppa:tamkungz/stable
sudo apt update
sudo apt install tarminal

sudo tee /etc/yum.repos.d/tamkungz-packages.repo >/dev/null <<'EOF'
[tamkungz-packages]
name=TamKungZ Packages
baseurl=https://packages.tamkungz.me/rpm/$basearch/
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://packages.tamkungz.me/gpg.key
EOF

sudo dnf makecache
sudo dnf install tarminal

openSUSE Tumbleweed

sudo zypper ar https://download.opensuse.org/repositories/home:/TamKungZ_/openSUSE_Tumbleweed/home:TamKungZ_.repo
sudo zypper refresh
sudo zypper install tarminal

Alpine (APK)

sudo mkdir -p /etc/apk/keys
curl -fsSL https://packages.tamkungz.me/apk/tamkungz.rsa.pub | \
  sudo tee /etc/apk/keys/tamkungz.rsa.pub >/dev/null

echo "https://packages.tamkungz.me/apk" | \
  sudo tee -a /etc/apk/repositories

sudo apk update
sudo apk add tarminal

sudo mkdir -p /etc/xbps.d
sudo tee /etc/xbps.d/tamkungz.conf >/dev/null <<'EOF'
repository=https://packages.tamkungz.me/xbps/$XBPS_ARCH
EOF

sudo xbps-install -S
sudo xbps-install tarminal

curl -fsSL https://packages.tamkungz.me/gpg.key | sudo pacman-key --add -
sudo pacman-key --lsign-key release@tamkungz.me || true

sudo tee -a /etc/pacman.conf >/dev/null <<'EOF'
[tamkungz]
Server = https://packages.tamkungz.me/arch/$arch
SigLevel = DatabaseRequired PackageOptional
EOF

sudo pacman -Sy
sudo pacman -S tarminal

Published Packages — v0.2.0

GitHub Releases also publish standalone Linux binaries, .deb, .rpm, .tar.xz, SHA256SUMS, and detached .asc signatures. Full list on GitHub Releases →

Developer Packages

• Rust crate: use the installer core directly from Rust applications.
• Python bindings: reuse the shared library from Python tools.

Usage

# Inspect tarball
tarminal inspect ./myapp-1.2.0-linux-x64.tar.xz

# Install with automatic detection
tarminal install ./myapp.tar.xz

# Manual config prompts
tarminal install ./app.tar.xz --config

# Use a recipe file
tarminal install ./app.tar.xz --recipe ./app.tarapp.yml

# System-wide install
sudo tarminal install ./app.tar.xz --system

# List installed apps (shows 'unknown' if no reliable version found)
tarminal list

# Remove an app
tarminal remove myapp

# Check installed app
tarminal doctor myapp

tarminal --help

Installation Paths

App files:   ~/.local/share/tarapp/apps/<app-id>/
Command:     ~/.local/bin/<command>
Desktop:     ~/.local/share/applications/<app-id>.desktop
Icon:        ~/.local/share/icons/hicolor/256x256/apps/<app-id>.*
State DB:    ~/.local/state/tarapp/apps.json

App files:   /opt/<app-id>/
Command:     /usr/local/bin/<command>
Desktop:     /usr/share/applications/<app-id>.desktop
Icon:        /usr/share/icons/hicolor/256x256/apps/<app-id>.*
State DB:    /var/lib/tarapp/apps.json

Supported Archives & Detection

Archive formats: .tar.xz, .txz, .tar.gz, .tgz, .tar.bz2, .tbz2, .tar

Filename detection

Tarminal first tries to infer app metadata from common filename shapes:

<app>-<version>-<os>-<architecture>.tar.xz
<app>_<version>_<os>_<architecture>.tar.xz

Executable detection

It then inspects the archive contents and looks for likely executable candidates, including names that match:

<app>
<app>-<architecture>
<app>_<architecture>
bin/<app>

If detection isn't good enough for a given tarball, fall back to tarminal install ./app.tar.xz --config or provide a recipe (below).

Detection fallback

1. user-provided CLI / config / recipe version
2. reliable archive filename parsing
3. app metadata inside the installed directory (product-info.json, package.json, VERSION, etc.)
4. runtime command probing (--version, -version, -v, version, -V)
5. unknown/None if nothing reliable was found

Recipe Format

External: --recipe ./app.tarapp.yml  |  Embedded (inside the archive): tarapp.yml, tarapp.yaml, .tarapp.yml, .tarapp.yaml, manifest.yml, manifest.yaml

id: com.example.myapp
name: My App
version: 1.0.0
exec: MyApp
command: myapp
icon: assets/icon.png
desktop:
  categories:
    - Utility
  terminal: false

Recipes are optional, but they are the recommended way for communities or app authors to make tarball installs reliable.

Build From Source

cargo build --workspace
cargo build --release -p tar-install --bin tar-install
cargo build --release -p tarminal

Rust workspace — tar-install library + tarminal CLI frontend.

Safety Behavior

Tarminal refuses to install archives with unsafe entries, regardless of recipe or CLI flags:

• absolute paths
• .. path traversal
• unsafe or absolute symlink targets
• hard-link entries (still unsupported)

Relative symlinks are allowed only when they resolve inside the extracted app tree. Anything that points outside the app tree is rejected.

Package Locally

Install the packaging tools once:

cargo install cargo-deb cargo-generate-rpm

cargo deb -p tar-install
cargo deb -p tarminal

cargo build --release -p tar-install --bin tar-install
cargo build --release -p tarminal

cargo generate-rpm -p crates/tar-install
cargo generate-rpm -p crates/tarminal

for deb in target/debian/*.deb; do
  dpkg -I "$deb"
  dpkg -c "$deb"
done

for rpm in target/generate-rpm/*.rpm; do
  rpm -qpi "$rpm"
  rpm -qpl "$rpm"
  rpm -qpR "$rpm"
done

Release Process

Releases are handled by GitHub Actions when a version tag is pushed:

git tag v0.2.0
git push origin v0.2.0

The workflow builds packages, signs artifacts, creates the GitHub Release, and publishes package-repository files to packages.tamkungz.me:

/gpg.key
/apt
/rpm/x86_64
/apk
/xbps
/arch
/apps/tarminal

/apps/tarminal is only this landing/documentation page — package managers install from /apt and /rpm/$basearch (and the Alpine/Void/Arch repositories above) directly.

Tagged releases also publish GitHub Release assets, OBS sources for openSUSE Tumbleweed, AUR PKGBUILD updates when credentials are configured, the tar-install crate on crates.io, and Python bindings through the pylib-tar-install workflow.

Project Structure

crates/
  tar-install/
    src/lib.rs          library exports
    src/bin/            hint command binary
    src/archive.rs      inspect tarball, detect binary/icon/manifest
    src/filename.rs     parse <app>-<version>-<os>-<arch>
    src/install.rs      install/remove/doctor logic
    src/ffi.rs          C ABI used by Python bindings
    src/desktop.rs      .desktop generation
    src/paths.rs        user/system install targets
    src/recipe.rs       manifest/recipe schema
    src/state.rs        installed apps database

  tarminal/
    src/main.rs         CLI frontend

pylib-tar-install/
  python/tarinstall/    Python bindings around libtar_install.so

Status

This is an early prototype designed for iteration — but the important architecture is already separated:

• tar-install can be reused by other GUIs or tools
• tarminal is only a CLI wrapper around it
• recipes are optional but first-class
• --config lets people fix bad filename/archive detection
• package publishing is automated for GitHub Releases and packages.tamkungz.me
• tar-install is published for Rust and Python developers

Changelog

# Clean up old root-user install if needed
sudo tarminal remove blender --scope user