diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dcfe2a3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,40 @@
+# unhinged-traefik
+
+The traefik ingress and service discovery component of the unhinged cluster stack. Relies on docker
+
+## Supported Labels
+
+| Label                           | Description                                                                                       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------- |
+| com.keganmyers.unhinged.http    | An [HttpAnnouncement](#HttpAnnouncement)                                                          |
+| com.keganmyers.unhinged.http.\* | An [HttpAnnouncement](#HttpAnnouncement), used when you need more than one for a single container |
+
+## Configuration
+
+### HttpAnnouncement
+
+```
+{
+  "name": "git",                          // required, name of service
+  "rule": "Host(`git.keganmyers.com`)",   // required, the host rule for the http router
+  "port": 3009,                           // required, the port for the server on the http service
+  "entrypoints": ["web"],                 // required, which entrypoints to listen on
+  "middlewares": ["foo", "bar@provider"], // optional, the _names_ of any middlewares to attach to this router
+  // todo: protocol
+  // todo: transport
+}
+```
+
+## components
+
+### unhinged-traefik-announcer
+
+Finds relevant labels on containers, and announces them to a server.
+
+This is packaged as an executable using [`pkg`](https://github.com/vercel/pkg), and intended to be run via systemd. The server to announce to is defined via the `URL` environment variable, such as `URL=ws://127.0.0.1`.
+
+### unhinged-traefik-server
+
+A server that listens for announcements and retractions, then generates a configuration for traefik to consume through its [HTTP configuration provider](https://doc.traefik.io/traefik/providers/http/).
+
+This is packaged as a docker container.