diff --git a/docs/source/rug.rst b/docs/source/rug.rst
index b39320c..67cfed0 100644
--- a/docs/source/rug.rst
+++ b/docs/source/rug.rst
@@ -92,7 +92,48 @@ The supported states in the state machine are:
         transition is utilized to add routers back into management after issues
         are resolved and signal to :py:mod:`akanda-rug` that it should attempt
         to manage them again.
-    
+
+    :STATS: Reads traffic data from the router.
+
+    :CONFIG: Configures the VM and its services.
+
+    :EXIT: Processing stops.
+
+
+ACT(ion) Variables are:
+
+    :Create: Create router was requested.
+
+    :Read: Read router traffic stats.
+
+    :Update: Update router configuration.
+
+    :Delete: Delete router.
+
+    :Poll: Poll router alive status.
+
+    :rEbuild: Recreate a router from scratch.
+
+VM Variables are:
+
+    :Down: VM is known to be down.
+
+    :Booting: VM is booting.
+
+    :Up: VM is known to be up (pingable).
+
+    :Configured: VM is known to be configured.
+
+    :Restart Needed: VM needs to be rebooted.
+
+    :Hotplug Needed: VM needs to be replugged.
+
+    :Gone: The router definition has been removed from neutron.
+
+    :Error: The router has been rebooted too many times, or has had some
+            other error.
+
+.. graphviz:: state_machine.dot
 
 .. _health:
 
diff --git a/docs/source/state_machine.dot b/docs/source/state_machine.dot
new file mode 100644
index 0000000..4c037e2
--- /dev/null
+++ b/docs/source/state_machine.dot
@@ -0,0 +1,57 @@
+digraph rug {
+  // rankdir=LR;
+
+  node [shape = rectangle];
+  START;
+
+  // These nodes enter and exit the state machine.
+
+  node [shape = doublecircle];
+  EXIT;
+  CALC_ACTION;
+
+  node [shape = circle];
+
+  START -> CALC_ACTION;
+
+  CALC_ACTION -> ALIVE [ label = "ACT>[CRUP],vm:[UC]" ];
+  CALC_ACTION -> CREATE_VM [ label = "ACT>[CRUP],vm:D" ];
+  CALC_ACTION -> CHECK_BOOT [ label = "ACT>[CRUP],vm:B" ];
+  CALC_ACTION -> REBUILD_VM [ label = "ACT:E" ];
+  CALC_ACTION -> STOP_VM [ label = "ACT>D or vm:G" ];
+  CALC_ACTION -> CLEAR_ERROR [ label = "vm:E" ];
+
+  ALIVE -> CREATE_VM [ label = "vm>D" ];
+  ALIVE -> CONFIG [ label = "ACT:[CU],vm:[UC]" ];
+  ALIVE -> STATS [ label = "ACT:R,vm:C" ];
+  ALIVE -> CALC_ACTION [ label = "ACT:P,vm>[UC]" ];
+  ALIVE -> STOP_VM [ label = "vm:G" ];
+
+  CREATE_VM -> CHECK_BOOT [ label = "ACT:[CRUDP],vm:[DBUCR]" ];
+  CREATE_VM -> STOP_VM [ label = "vm:G" ];
+  CREATE_VM -> CALC_ACTION [ label = "vm:E" ];
+  CREATE_VM -> CREATE_VM [ label = "vm:D" ];
+
+  CHECK_BOOT -> CONFIG [ label = "vm>U" ];
+  CHECK_BOOT -> CALC_ACTION [ label = "vm:[BCR]" ];
+  CHECK_BOOT -> STOP_VM [ label = "vm:[DG]" ];
+
+  CONFIG -> STATS [ label = "ACT:R,vm>C" ];
+  CONFIG -> CALC_ACTION [ label = "ACT>P,vm>C" ];
+  CONFIG -> REPLUG_VM [ label = "vm>[H]" ];
+  CONFIG -> STOP_VM [ label = "vm>[RDG]" ];
+
+  REPLUG_VM -> CONFIG [ label = "vm>[H]" ];
+  REPLUG_VM -> STOP_VM [ label = "vm>[R]" ];
+
+  STATS -> CALC_ACTION [ label = "ACT>P" ];
+
+  CLEAR_ERROR -> CALC_ACTION [ label = "no pause before next action" ];
+
+  REBUILD_VM -> REBUILD_VM [ label = "vm!=[DG]" ];
+  REBUILD_VM -> CREATE_VM [ label = "ACT:E,vm:D" ];
+
+  STOP_VM -> CREATE_VM [ label = "ACT:E or vm>D" ];
+  STOP_VM -> EXIT [ label = "ACT:D,vm>D or vm:G" ];
+
+}