Skip to content

Debug Shell

New in OrbStack 1.5

Read the blog post

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.

Debug Shell button

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

bash
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:

bash
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:

bash
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:

bash
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.

bash
 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:

Debug Shell