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). You can debug containers running on remote Docker hosts in addition to local containers.

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>

Remote debugging ​

It's also possible to debug containers running on remote Docker hosts — for example, on production servers. To connect to a remote Docker host, add a Docker CLI context with your remote host's address and credentials (SSH, TLS certificates, or plain TCP). For example, to connect to a remote host at 192.168.1.100 using SSH, run:

docker context create servy --docker host=ssh://user@192.168.1.100
# list running containers on the remote host
docker ps -c servy

docker context create servy --docker host=ssh://user@192.168.1.100
# list running containers on the remote host
docker ps -c servy

Then, you can use the servy context to debug containers on that host:

orb debug -c servy <container name or ID>

orb debug -c servy <container name or ID>

This uses the same contexts as the docker command, so if you already have a context for your remote host, you can use that.

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: