Debug Shell ​

OrbStack Debug Shell provides useful commands & tools, making it easy to debug any container (even minimal/distroless/read-only containers that have no shell or commands).

Compared to docker exec, Debug Shell has:

• Shell auto-complete and syntax highlighting
• Editors (nano, vim)
• Common tools (htop, curl, strace, ip, etc.)
• Colorful output in ls and other commands
• Package manager with over 80,000 packages
• Works with distroless and read-only containers

Debug Shell makes it possible to build minimal, distroless container images that are small and secure, while still being able to debug them.

Usage ​

To start a Debug Shell in a new terminal, open a container in the app and click the "Debug" button.

You can also start a Debug Shell from the command line:

orb debug <container name or ID>

orb debug <container name or ID>

Packages ​

Inside the Debug Shell, use dctl to install packages. For example, to install neovim, run:

dctl install nvim

dctl install nvim

There's no need to search for package names—just use the name of the command you want to install. You can also run commands directly and OrbStack will automatically ask to install the package.

❯ emacs
emacs: command not found
  * install package 'emacs'? [y/N]

❯ emacs
emacs: command not found
  * install package 'emacs'? [y/N]

Installed packages are available across all containers, as long as you're using Debug Shell.

Installing and removing packages does not modify the container, so it works even in read-only containers.

Several tools are included: