diff --git a/README.md b/README.md
index 4eeb2cf..4a5f20d 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,62 @@
 # gearbsd
 
+This repo will eventually turn into a collection of parametrized templates to easily deploy services or environments on $system.
+
+# Examples
+
+- Deploying a pf.conf on OpenBSD
+- Enabling Gnome3 on OpenBSD (requires enabling many services, modifying /etc/login.conf and /etc/gdm.conf)
+
+# Why?
+
+Most of the time we need to do the same things over and over, using simple templates with parameters allow easy reproducibles configuration.
+
+# How to use
+
+You need [(R)?ex](https://rexify.org/) installed, cd into a directory to find a `Rexfile`, look at the self explanatory variables at the top of the file to adapt your needs and run `rex -H destination configure`, on localhost you can run it as root like `rex configure` or `rex -H localhost configure` if you have a localhost root access by ssh.  You will need root access through ssh when using Rex over the network.
+
+# Improvements
+
+- Allow to use sudo instead of direct root access
+- Allow to use doas (but this will require changes in Rex)
+- Maintain a list of applied modules to keep track of used modules
+
+# Template example
+
+In the `openbsd/pf` module, these variables will define the generation of the pf.conf file.
+
+- TCPports: [22, 80, 443]
+- UDPports: [53, "2000:20010"]
+- allow_icmp: 1
+- nat: 0
+- nat_from_interface: "wg0"
+- nat_to_interface: "em0
+
+This set of values will produce the following file and load it into pf:
+```
+services_tcp="{ 22 80 443 }"
+services_udp="{ 53 2000:20010 }"
+
+set skip on lo
+set block-policy drop
+
+# block incoming by default
+block return log
+pass out quick
+
+# allow TCP
+pass in on egress inet proto tcp from any to (egress) port $services_tcp
+
+# allow UDP
+pass in on egress inet proto udp from any to (egress) port $services_udp
+
+# allow ICMP (over ipv4)
+pass in on egress inet proto icmp from any to (egress)
+
+# <-- default rules --->
+# By default, do not permit remote connections to X11
+block return in on ! lo0 proto tcp to port 6000:6010
+
+## Port build user does not need network
+block return out log proto {tcp udp} user _pbuild
+```