1 files changed, 32 insertions, 0 deletions
diff --git a/ingress/README.md b/ingress/README.md
new file mode 100644
index 0000000..d4a8338
--- /dev/null
+++ b/ingress/README.md
@@ -0,0 +1,32 @@
+# YAMN Nym ingress
+
+This service receives an envelope over the Nym mixnet and delivers the
+already encrypted YAMN packet to an allowlisted SMTP entry through Tor.
+
+The Nym address is generated by the persistent client identity and printed at
+startup. It must be copied to `YAMN_NYM_RECIPIENT` on the sending web service.
+
+Required environment:
+
+- `YAMN_ALLOWED_ENTRY_ADDRESSES`: comma-separated exact YAMN entry addresses.
+- `YAMN_NYM_INGRESS_STORAGE`: persistent directory for the Nym identity.
+
+Optional environment:
+
+- `YAMN_TOR_SOCKS`, default `127.0.0.1:9050`.
+- `YAMN_INGRESS_FROM`, default `<>`.
+- `YAMN_DRY_RUN`, default false. When enabled, valid envelopes are accepted but
+  not delivered to SMTP, for non-delivery integration tests.
+
+Input protocol, sent as the Nym message body:
+
+```json
+{"version":1,"entry_address":"yamn@example.org","payload":"<base64 raw SMTP envelope>"}
+```
+
+The service does not log payloads, sender identities, or recipient message
+contents. It has no reply, fetch, view, inbox, or fallback-direct-SMTP mode.
+
+An example systemd unit and environment file are in `deploy/`. The production
+environment file must be reviewed against the current YAMN remailer list and
+must not be committed if it contains deployment-specific secrets.