Xray

A blazing fast layer inspector for OCI-compliant images!

Xray helps developers understand and optimize container images by visualizing layers and their contents using a minimalistic but powerful UI with performance in mind.

• 🛠️ Supports Vim motions and has fully customizable keybindings.
• 📌 Relatively small memory footprint (~80Mb for an 8Gb image).
• 🗒️ Supports path filtering (with full RegEx support).
• ⛓️ Supports size-based filtering.
• 🚀 Fast startup times due to optimized image parsing.
• 🏡 Convenient and minimalistic UI.
• 🎨 ANSI theme-aware colors that follow your terminal palette.
• 📦 Works with any OCI-compliant container image.
• ⚙️ No needless re-rendering of the UI: xray values your CPU cycles.

This is essentially a beta release at this point, so don't hesitate to open an issue if you find any bugs while using it 🍀

⚠️ Requires the nightly compiler

# If Rust nightly wasn't installed before
$ rustup toolchain install nightly
$ cargo +nightly install --locked xray-tui

paru -Sy xray-oci-git

Everyone who had to work with container images before knows about the dive tool. It's a great tool, but it doesn't work that well for bigger images, especially the ones that are 5 GB or more in size.

Xray fixes this problem by carefully managing available resources and applying a set of small but important optimizations. All these things make Xray far more responsive when used with large images, while still providing the core functionality and being easy to use.

$ xray --help
Usage: xray [OPTIONS] <IMAGE>

Arguments:
  <IMAGE>


Options:
  -p, --config-path <CONFIG_PATH>
          Override the config directory location.

          Default: $XDG_CONFIG_HOME/xray or $HOME/.config/xray

  -d, --docker
          Force image resolution using Docker

  -f, --fs
          Force image resolution using a tarred image

      --podman
          Force image resolution using Podman

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

To inspect an image use:

xray <IMAGE>[:tag]

xray will try to resolve the provided image using the default resolution order:

1. Look for a tarred repository with image locally (treating the provided argument as a path).
2. Try to resolve the image using Docker.
3. Try to resolve the image using Podman.

💡 Please refer to xray --help if you want to force a specific image resolver.

💡 You can always use the help popup available by pressing / to get the contextualized help for the currently active pane.

All keybindings mentioned above are fully customizable.

When run for the first time, xray creates a file named $CONFIG_DIR/keybinds.toml, which contains all default keybindings and their description.

💡Default $CONFIG_DIR is $XDG_CONFIG_HOME/xray or $HOME/.config/xray.

Runtime state such as xray.log is stored in $XDG_STATE_HOME/xray or $HOME/.local/state/xray.

You can then update the default keybindings to your liking -- xray will start using your new bindings automatically after a restart!

For example, if you want to open the filter popup on ALT+p, then you can change toggle_filter_popup to look like:

# Toggle the filtering popup.
toggle_filter_popup = ["Alt+p"]

Please refer to crossterm-keybind documentation if you are unsure how to map a specific key sequence.

• Opaque whiteouts are not handled properly
• Some panes are missing the vertical/horizontal scroll feature, which may cause issues in certain contexts

This section contains additional good-to-have things that I plan to add besides fixing everything in the Limitations section.

• Reduce the memory footprint further
• Add unit and fuzz tests
• Improve the scrolling behaviour in the "Layer Changes" tab
• Add more installation options
• Add layer caching

Xray is distributed under the GNU General Public License version 3. See COPYING for full details.