Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,22 @@ Towel installs a `towel` command and a predefined Distrobox container config for
- installing packages with `dnf` inside the container,
- exporting app launchers/binaries back to the host via managed wrappers.

## Requirements

Towel runs on a Linux host (including WSL2) and uses **rootless [Podman](https://podman.io/)** as its container engine. You need:

- **bash**
- **[Podman](https://podman.io/)** — towel manages the container through it directly, and the bundled Distrobox config sets `container_manager="podman"`
- **curl** — used by the installer to download Distrobox
- **[Distrobox](https://distrobox.it/)** — installed automatically by `./install` if it isn't already present (pinned version, checksum-verified)

Install Podman with your distribution's package manager, for example:

```bash
sudo dnf install -y podman # Fedora
sudo apt-get install -y podman # Debian/Ubuntu
```

## Quick start

### 1) Install towel
Expand Down Expand Up @@ -66,6 +82,24 @@ towel update --check # check for updates
towel update --apply # install latest release
```

## Updating towel

Towel checks for a new release automatically (at most once per day) and prints a notice when one is available. You can also check or update on demand:

```bash
towel update --check # report whether a newer release exists (exit 10 if so)
towel update --apply # download, verify the checksum, and install the latest release
```

To turn the automatic check off (or back on):

```bash
towel update --no-auto-check # disable the daily check
towel update --auto-check # re-enable it
```

Setting `TOWEL_NO_UPDATE_CHECK=1` in your environment also disables the automatic check.

## How export works

Exported integrations are managed by towel and placed under:
Expand Down Expand Up @@ -106,6 +140,19 @@ Apps that require behavior outside towel’s export/runtime model, for example:

These can still run manually in some cases, but won’t be reliably auto-exported by `towel export`.

## Uninstalling

```bash
towel remove # remove the container and any exported app wrappers
rm -f ~/.local/bin/towel
rm -rf ~/.local/share/towel
rm -f ~/.config/distrobox/towel.ini
```

The installer also copied `~/.config/distrobox/distrobox.conf` and `~/.config/containers/storage.conf` (backing up any pre-existing versions with a `.bak.*` suffix). These are shared Distrobox/Podman settings — only remove them if you don't use Distrobox for anything else, and restore your backup if you had one.

If the installer added a `~/.local/bin` PATH line to your `~/.bashrc` or `~/.zshrc`, you can remove that too.

## Notes

- `towel remove` is destructive and unexports managed wrappers first.
Expand Down