GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • OrbStack Docs
  • Docker
  • Linux
  • Install
  • Demo
  • Features
  • Frequently asked questions
  • What's new
  • Install
  • Efficiency
  • Benchmarks
  • Architecture
  • Settings
  • Licensing

This view

  • Original page
  • New address

GeezerVison is showing docs.orbstack.dev — Debug Shell · OrbStack Docs

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, right-click a container in the app and choose "Debug Shell".

Debug Shell 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:

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

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

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.