diff --git a/README.md b/README.md
index 05526484..d271aa15 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,16 @@
 # fakemachine - fake a machine
 
-Creates a virtual machine based on the currently running system.
+fakemachine creates a virtual machine derived from the current root filesystem
+and allows the user to run commands inside it.
+
+It is provided as a standalone executable as well as a Go library and is
+primarily used by [debos](https://github.com/go-debos/debos) to execute image
+build actions inside a VM. This gives stronger isolation than chroot and allows
+unprivileged users to perform operations that would normally require root on the
+host, such as mounting filesystem images.
+
+If fakemachine is ran inside a container, the virtual machine's root filesystem
+is derived from the container's root filesystem.
 
 ## Synopsis
 
diff --git a/doc/man/fakemachine.1 b/doc/man/fakemachine.1
index 8cf6c468..cd67bdbb 100644
--- a/doc/man/fakemachine.1
+++ b/doc/man/fakemachine.1
@@ -4,7 +4,21 @@
 .SH NAME
 fakemachine \- fake a machine
 .PP
-Creates a virtual machine based on the currently running system.
+fakemachine creates a virtual machine derived from the current root
+filesystem and allows the user to run commands inside it.
+.PP
+It is provided as a standalone executable as well as a Go library and is
+primarily used by \c
+.UR https://github.com/go-debos/debos
+debos
+.UE \c
+\ to execute image build actions inside a VM.
+This gives stronger isolation than chroot and allows unprivileged users
+to perform operations that would normally require root on the host, such
+as mounting filesystem images.
+.PP
+If fakemachine is ran inside a container, the virtual machine\(cqs root
+filesystem is derived from the container\(cqs root filesystem.
 .SH SYNOPSIS
 .IP
 .EX
diff --git a/doc/man/fakemachine.md b/doc/man/fakemachine.md
index c06040bf..516209f9 100644
--- a/doc/man/fakemachine.md
+++ b/doc/man/fakemachine.md
@@ -5,7 +5,17 @@
 fakemachine - fake a machine
 
 
-Creates a virtual machine based on the currently running system.
+fakemachine creates a virtual machine derived from the current root filesystem
+and allows the user to run commands inside it.
+
+It is provided as a standalone executable as well as a Go library and is
+primarily used by [debos](https://github.com/go-debos/debos) to execute image
+build actions inside a VM. This gives stronger isolation than chroot and allows
+unprivileged users to perform operations that would normally require root on the
+host, such as mounting filesystem images.
+
+If fakemachine is ran inside a container, the virtual machine's root filesystem
+is derived from the container's root filesystem.
 
 # SYNOPSIS