From 956c8ab71a0d5361a1e11a692e1e5e9afef2a4c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hern=C3=A2ni=20Marques?= <hernani+magikoopa@vecirex.net>
Date: Thu, 16 Jul 2026 15:04:00 +0200
Subject: [PATCH] configs/nym: add Nym (nym.com) node README skeleton

---
 configs/nym/README.md | 54 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 configs/nym/README.md

diff --git a/configs/nym/README.md b/configs/nym/README.md
new file mode 100644
index 0000000..94a2a78
--- /dev/null
+++ b/configs/nym/README.md
@@ -0,0 +1,54 @@
+# Nym node — koopa (`koopa-nym`)
+
+Podman container **`koopa-nym`** runs a [**nym-node**](https://nym.com/docs/operators/nodes/nym-node)
+from [nym.com](https://nym.com/) (Nym mixnet / NymVPN network).  
+Host layout (live): `~/koopa-nym/`.  
+Mirror in this repo: `configs/nym/`.
+
+| Setting | Value |
+|---------|--------|
+| Container | `koopa-nym` |
+| Image | `localhost/koopa-nym:latest` |
+| Default mode | **`mixnode`** (safest on a home host; no open-internet exit) |
+| Optional modes | `entry-gateway`, `exit-gateway` (+ WireGuard for dVPN) — see env |
+| Local ID | `koopa-nym` |
+| Data | `~/.nym/nym-nodes/koopa-nym/` inside volume `./data` |
+| Operator T&Cs | must pass `--accept-operator-terms-and-conditions` every run |
+
+## Ports (host) — avoid Caddy **9000/9001** and Tor **8080**
+
+| Role | nym-node default | Host publish |
+|------|------------------|--------------|
+| HTTP API / swagger | `8080` | **9080** |
+| Mixnet Sphinx | `1789` | **1789** |
+| Verloc | `1790` | **1790** |
+| Entry client WS | `9000` | **19000** (only if gateway mode) |
+| WireGuard | `51822` | **51822** (only if WG enabled) |
+
+VeciGate / firewall: open only what the chosen mode needs.  
+**Exit-gateway** and **WireGuard** expose the host IP to abuse complaints — read
+[Nym exit counsel](https://nym.com/docs/operators/community-counsel/exit-gateway)
+before enabling.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Containerfile` | Debian slim + nym-node binary |
+| `entrypoint.sh` | env → `nym-node run …` |
+| `compose.yml` | podman/docker compose |
+| `.env.example` | non-secret knobs |
+| `container-koopa-nym.service` | systemd --user unit template |
+
+## Ops (sketch)
+
+```bash
+cd ~/koopa-nym   # or this mirror
+cp .env.example .env   # edit PUBLIC_IPS, LOCATION, MODE
+podman build -t localhost/koopa-nym:latest -f Containerfile .
+podman compose up -d   # or podman run …
+# bonding: use Nym wallet / harbourmaster; node must accept operator T&Cs
+curl -sS http://127.0.0.1:9080/api/v1/roles | jq .
+```
+
+Secrets / wallet mnemonics never live in this repo — see root `SECRETS.md`.