Orbstack Debug Shell [March 2024]

1 hour ago 2

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:

bash

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://[email protected] # list running containers on the remote host docker -c servy ps

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

bash

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:

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]

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