Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 19. Using Toolbx for development and troubleshooting

Use Toolbx containers to install development tools without modifying the host system. Toolbx provides a seamless environment where you can access host resources while keeping your system clean.

Installing software on a system presents certain risks: it can change a system’s behavior, and can leave unwanted files and directories behind after they are no longer needed. You can prevent these risks by installing your favorite development and debugging tools, editors, and software development kits (SDKs) into the Toolbx fully mutable container without affecting the base operating system. You can perform changes on the host system with commands such as less, lsof, rsync, ssh, sudo, and unzip.

You can install development tools and SDKs in a Toolbx container to avoid system changes and unwanted files on your base operating system. You can also perform changes on the host system with commands such as less, lsof, rsync, ssh, sudo, and unzip. The Toolbx utility performs the following actions:

  1. Pulling the registry.access.redhat.com/ubi10/toolbox:latest image to your local system
  2. Starting up a container from the image
  3. Running a shell inside the container from which you can access the host system
Note

Whether a Toolbx container runs as a root or rootless container depends on the rights of the user who creates it. You should also run utilities that require root rights on the host system in root containers.

19.1. Starting a Toolbx container
Copy link

You can start a Toolbx container to enter an isolated environment for development or troubleshooting. Entering the container ensures you can install and run command-line tools without modifying the underlying host operating system.

Procedure

  1. Create a Toolbx container:

    • As a rootless user: 

      $ toolbox create <mytoolbox>
Created container: <mytoolbox>
Enter with: toolbox enter <mytoolbox>
      Copy to Clipboard Toggle word wrap

    • As a root user: 

      $ sudo toolbox create <mytoolbox>
Created container: <mytoolbox>
Enter with: toolbox enter <mytoolbox>
      Copy to Clipboard Toggle word wrap

    • Verify that you pulled the correct image: 

      [user@toolbox ~]$ toolbox list
IMAGE ID      IMAGE NAME    CREATED
fe0ae375f149   registry.access.redhat.com/ubi10/toolbox:latest 5 weeks ago

CONTAINER ID  CONTAINER NAME  CREATED         STATUS   IMAGE NAME
5245b924c2cb  <mytoolbox>       7 minutes ago   created  registry.access.redhat.com/ubi10/toolbox:latest
      Copy to Clipboard Toggle word wrap

  2. Enter the Toolbx container: 

    [user@toolbox ~]$ toolbox enter <mytoolbox>
    Copy to Clipboard Toggle word wrap

Verification

  • Enter a command inside the <mytoolbox> container and display the name of the container and the image: 

    ⬢ [user@toolbox ~]$ cat /run/.containerenv
engine="podman-4.8.2"
name="<mytoolbox>"
id="5245b924c2cb..."
image="registry.access.redhat.com/ubi10/toolbox:latest"
imageid="fe0ae375f14919cbc0596142e3aff22a70973a36e5a165c75a86ea7ec5d8d65c"
    Copy to Clipboard Toggle word wrap

19.2. Using Toolbx for development
Copy link

You can use a Toolbx container as a rootless user for installation of development tools, such as editors, compilers, and software development kits (SDKs). After installation, you can continue using those tools as a rootless user.

Prerequisites

  • The Toolbx container is created and is running. You entered the Toolbx container. You do not need to create the Toolbx container with root privileges. See Starting a Toolbox container.

Procedure

  • Install the tools of your choice, for example, the Emacs text editor, GCC compiler and GNU Debugger (GDB): 

    ⬢[user@toolbox ~]$ sudo dnf install emacs gcc gdb
    Copy to Clipboard Toggle word wrap

Verification

  • Verify that the tools are installed: 

    ⬢[user@toolbox ~]$  dnf repoquery --info --installed <package_name>
    Copy to Clipboard Toggle word wrap

You can use a Toolbx container with root privileges to find the root cause of various problems with the host system by using tools such as systemctl, journalctl , and nmap, without installing them on the host system.

Prerequisites

  • The Toolbx container is created and is running. You entered the Toolbx container. You need to create the Toolbx container with root privileges. See Starting a Toolbox container.

Procedure

  1. Install the systemd package to be able to run the journalctl command: 

    ⬢[root@toolbox ~]# dnf install systemd
    Copy to Clipboard Toggle word wrap

  2. Display log messages for all processes running on the host: 

    ⬢[root@toolbox ~]# j journalctl --boot -0
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: microcode: updated ear>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Linux version 6.6.8-10>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Command line: BOOT_IMA>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: x86/split lock detecti>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-provided physical>
    Copy to Clipboard Toggle word wrap

  3. Display log messages for the kernel: 

    ⬢[root@toolbox ~]# journalctl --boot -0 --dmesg
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: microcode: updated ear>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Linux version 6.6.8-10>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Command line: BOOT_IMA>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: x86/split lock detecti>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-provided physical>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-e820: [mem 0x0000>
    Copy to Clipboard Toggle word wrap

  4. Install the nmap network scanning tool: 

    ⬢[root@toolbox ~]# dnf install nmap
    Copy to Clipboard Toggle word wrap

  5. Scan IP addresses and ports in a network: 

    ⬢[root@toolbox ~]# nmap -sS scanme.nmap.org
Starting Nmap 7.93 ( https://nmap.org ) at 2024-01-02 10:39 CET
Stats: 0:01:01 elapsed; 0 hosts completed (0 up), 256 undergoing Ping Scan
Ping Scan Timing: About 29.79% done; ETC: 10:43 (0:02:24 remaining)
Nmap done: 256 IP addresses (0 hosts up) scanned in 206.45 seconds
    Copy to Clipboard Toggle word wrap
    • The -sS option performs a TCP SYN scan. Most of Nmap’s scan types are only available to privileged users, because they send and receive raw packets, which requires root access on UNIX systems.

19.4. Stopping the Toolbx container
Copy link

You can stop an active Toolbx container to release system resources and conclude your development session. Ending the container process ensures that background tasks are terminated, enabling you to maintain a clean and efficient environment for subsequent workloads.

Use the exit command to leave the Toolbox container and the podman stop command to stop the container.

Procedure

  1. Leave the container and return to the host: 

    ⬢ [user@toolbox ~]$ exit
    Copy to Clipboard Toggle word wrap

  2. Stop the toolbox container: 

    ⬢ [user@toolbox ~]$ podman stop <mytoolbox>
    Copy to Clipboard Toggle word wrap

  3. Optional: Remove the toolbox container: 

    ⬢ [user@toolbox ~]$ toolbox rm <mytoolbox>
    Copy to Clipboard Toggle word wrap

    Alternatively, you can also use the podman rm command to remove the container.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top