Debug Shell
New in OrbStack 1.5
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: