diff --git a/docs/building-and-running.md b/docs/building-and-running.md
new file mode 100644
index 000000000..1231a4d14
--- /dev/null
+++ b/docs/building-and-running.md
@@ -0,0 +1,96 @@
+# Building and Running
+
+## Building gnome-shell
+
+gnome-shell uses the [meson] build system, and can be compiled
+with the following commands:
+
+```sh
+$ meson setup _build
+$ meson compile -C _build
+```
+
+Unfortunately gnome-shell has a non-trivial number of dependencies
+that cannot always be satisfied by distribution packages.
+
+This is particular true for [mutter], which is developed in lock-step
+with gnome-shell and always has to be built from source.
+
+[meson]: https://mesonbuild.com/
+[mutter]: https://mutter.gnome.org
+
+## Toolbox
+
+[Toolbox][toolbox] is a container tool for Linux, which allows the use of
+interactive command line environments for development, without having to
+install software on the host.
+
+It is suitable for gnome-shell development, and we maintain a number of scripts
+to make its use easier and more convenient.
+
+You can set up a new container that satisfies all build- and runtime
+dependencies with the following script:
+
+```sh
+$ tools/toolbox/create-toolbox.sh
+```
+
+The script will download the container image and build mutter, so it is
+expected that it will take a while.
+
+Once you have a working container, the following scripts can be
+used to build and run gnome-shell:
+
+```sh
+$ tools/toolbox/meson-build.sh
+$ tools/toolbox/run-gnome-shell.sh
+```
+
+If building or running fails with errors about `meta`, `clutter` or `cogl`,
+there was probably an incompatible change in mutter. You can update the
+dependency with the following command:
+
+```sh
+$ toolbox run --container gnome-shell-devel update-mutter
+```
+
+Refer to the [README][toolbox-tools] for further information on the scripts.
+
+[toolbox]: https://containertoolbx.org/
+[toolbox-tools]: ../tools/toolbox/README.md
+
+## Running a nested instance
+
+It is possible to run gnome-shell as "nested" instance in a window.
+
+The `run-gnome-shell` script will automatically do that when run from
+a graphical session, or you can run the following command:
+
+```sh
+$ WAYLAND_DISPLAY=shell-test-1 dbus-run-session \
+    gnome-shell --wayland-display=shell-test-1 --nested
+```
+
+There are limitations to the nested instance, such as keyboard shortcuts
+usually not getting to the nested compositor.
+
+In order to still bring up the [Looking Glass][lg] debugger, you can
+use an [extension][lg-button] as workaround.
+
+[lg]: ./looking-glass.md
+[lg-button]: https://extensions.gnome.org/extension/2296/looking-glass-button/
+
+## Native
+
+Sometimes it's necessary to run the "native backend", on real display hardware.
+
+To do that, switch to a tty and either use the `run-gnome-shell` script
+or run the following command:
+
+```sh
+$ dbus-run-session gnome-shell --wayland
+```
+
+Some functionality is not available when running gnome-shell outside a GNOME
+session, including logout. To exit gnome-shell, bring up the run dialog with
+<kbd>Alt</kbd> <kbd>F2</kbd> and enter `debugexit`.