buildx/docs/guides/debugging.md

# Debug monitor

To assist with creating and debugging complex builds, Buildx provides a
debugger to help you step through the build process and easily inspect the
state of the build environment at any point.

> **Note**
>
> The debug monitor is a new experimental feature in recent versions of Buildx.
> There are rough edges, known bugs, and missing features. Please try it out
> and let us know what you think!

## Starting the debugger

To start the debugger, first, ensure that `BUILDX_EXPERIMENTAL=1` is set in
your environment.

```console
$ export BUILDX_EXPERIMENTAL=1
```

To start a debug session for a build, you can use the `--invoke` flag with the
build command to specify a command to launch in the resulting image.

```console
$ docker buildx build --invoke /bin/sh .
+] Building 4.2s (19/19) FINISHED
 => [internal] connecting to local controller                                                                                   0.0s
 => [internal] load build definition from Dockerfile                                                                            0.0s
 => => transferring dockerfile: 32B                                                                                             0.0s
 => [internal] load .dockerignore                                                                                               0.0s
 => => transferring context: 34B                                                                                                0.0s
 ...
Launching interactive container. Press Ctrl-a-c to switch to monitor console
Interactive container was restarted with process "dzz7pjb4pk1mj29xqrx0ac3oj". Press Ctrl-a-c to switch to the new container
Switched IO
/ #
```

This launches a `/bin/sh` process in the final stage of the image, and allows
you to explore the contents of the image, without needing to export or load the
image outside of the builder.

For example, you can use `ls` to see the contents of the image:

```console
/ # ls
bin    etc    lib    mnt    proc   run    srv    tmp    var
dev    home   media  opt    root   sbin   sys    usr    work
```

## Monitor mode

By default, when debugging, you'll be dropped into a shell in the final stage.

When you're in a debug shell, you can use the `Ctrl-a-c` key combination (press
`Ctrl`+`a` together, lift, then press `c`) to toggle between the debug shell
and the monitor mode. In monitor mode, you can run commands that control the
debug environment.

```console
(buildx) help
Available commands are:
  attach	attach to a buildx server or a process in the container
  disconnect	disconnect a client from a buildx server. Specific session ID can be specified an arg
  exec		execute a process in the interactive container
  exit		exits monitor
  help		shows this message
  kill		kill buildx server
  list		list buildx sessions
  ps		list processes invoked by "exec". Use "attach" to attach IO to that process
  reload	reloads the context and build it
  rollback	re-runs the interactive container with initial rootfs contents
```

## Build controllers

Debugging is performed using a buildx "controller", which provides a high-level
abstraction to perform builds. By default, the local controller is used for a
more stable experience which runs all builds in-process. However, you can also
use the remote controller to detach the build process from the CLI.

To detach the build process from the CLI, you can use the `--detach=true` flag with
the build command.

```console
$ docker buildx build --detach=true --invoke /bin/sh .
```

If you start a debugging session using the `--invoke` flag with a detached
build, then you can attach to it using the `buildx debug-shell` subcommand to
immediately enter the monitor mode.

```console
$ docker buildx debug-shell
+] Building 0.0s (1/1) FINISHED                                                                                                                                                                                
 => [internal] connecting to remote controller
(buildx) list
ID                              CURRENT_SESSION
xfe1162ovd9def8yapb4ys66t       false
(buildx) attach xfe1162ovd9def8yapb4ys66t
Attached to process "". Press Ctrl-a-c to switch to the new container
(buildx) ps
PID                             CURRENT_SESSION COMMAND
3ug8iqaufiwwnukimhqqt06jz       false           [sh]
(buildx) attach 3ug8iqaufiwwnukimhqqt06jz
Attached to process "3ug8iqaufiwwnukimhqqt06jz". Press Ctrl-a-c to switch to the new container
(buildx) Switched IO
/ # ls
bin    etc    lib    mnt    proc   run    srv    tmp    var
dev    home   media  opt    root   sbin   sys    usr    work
/ # 
```