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>

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 -c servy ps

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

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

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]

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: