@usex/mikrotik-mcp 4.7.0 → 4.9.0

package/prompts/setup-openvpn-tunnel-between-sites.md

@@ -0,0 +1,136 @@
+---
+name: setup-openvpn-tunnel-between-sites
+title: Build an OpenVPN (TLS) tunnel between two MikroTik devices
+description: Configure a MikroTik-to-MikroTik OpenVPN site-to-site link — certificates, PPP profile + secret, server + client, L3 (ip) or L2 (ethernet) mode, routing, firewall — over TCP/UDP 443 for HTTPS-like camouflage. Verified end to end, with DPI/censorship-bypass guidance.
+arguments:
+  - name: server_device
+    description: The device that will run the OpenVPN SERVER — reachable public IP/DDNS + a certificate. Config key or label from list_mikrotik_devices.
+    required: false
+  - name: client_device
+    description: The device that will run the OpenVPN CLIENT (may be behind NAT). Config key or label.
+    required: false
+  - name: mode
+    description: Tunnel mode — "ip" (L3 routed, default) or "ethernet" (L2 TAP, bridgeable across sites). Omit for ip.
+    required: false
+  - name: protocol
+    description: Transport — "tcp" (works with 443 camouflage, survives more DPI) or "udp" (faster). Omit for tcp when bypassing blocks, udp otherwise.
+    required: false
+  - name: port
+    description: Port for OpenVPN. 1194 is default; use 443 to look like HTTPS through restrictive networks. Omit for 1194.
+    required: false
+---
+
+You are building an **OpenVPN site-to-site tunnel between two MikroTik routers**.
+OpenVPN is a mature TLS VPN: it can be **L3 routed (`mode=ip`)** or **L2 bridgeable
+(`mode=ethernet`/TAP)**, over **TCP or UDP**, and on **any port** — running it on
+**TCP 443** makes it look like HTTPS, a strong DPI-bypass option (a different TLS
+fingerprint than SSTP). It is client↔server: one device is the **server** (reachable
+endpoint + certificate), the other the **client** (NAT-friendly). Drive both via the
+`device` argument. Confirm before writing — this touches certificates, PPP, and the
+firewall.
+
+Server device: {{server_device}}
+Client device: {{client_device}}
+Mode: {{mode}}
+Protocol: {{protocol}}
+Port: {{port}}
+
+## 0. Discover and assign roles (FIRST)
+
+- `list_mikrotik_devices`; resolve {{server_device}}/{{client_device}} — never
+  substitute a similar name; ask which is which if omitted.
+- The **server** must be reachable on the chosen `port`/`protocol` (static WAN or
+  DDNS). The **client** only needs outbound reach. Confirm roles.
+- Choose `mode`: **ip** for routed site-to-site (recommended default — cleaner,
+  faster); **ethernet** only if the user needs a stretched L2 domain (then bridge the
+  interface at both ends, with the same STP / single-DHCP warnings as EoIP/VXLAN).
+
+## 1. Facts (read-only, per device)
+
+Per side: `get_system_identity`, `list_ip_addresses`, `get_routing_table`,
+`get_ip_cloud`, and on the server `list_certificates`. Record server public
+address/DDNS, LAN subnets (must not overlap for `mode=ip`), and existing certs.
+
+## 2. Certificates
+
+OpenVPN needs a server certificate; with `require_client_certificate=true` it also
+needs a client cert (recommended — stronger than username/password alone):
+
+- If absent: `create_certificate` a CA → `sign_certificate` (self-signed); then a
+  **server** cert (CN=server address) and a **client** cert, each `sign_certificate`
+  by the CA.
+- `import_certificate` the CA (and client cert) onto the client. RouterOS OpenVPN
+  historically wants explicit certs on both ends — plan for it rather than relying on
+  username/password only.
+
+## 3. PPP profile + secret (server side)
+
+- `create_ppp_profile` — `local-address`=server tunnel IP, `remote-address`=client
+  tunnel IP or pool; optional DNS/routes.
+- `create_ppp_secret` — strong `name`/`password`, `service=ovpn`, `profile`=above.
+
+## 4. Enable the OpenVPN server (server side)
+
+`add_ovpn_server` (`device={{server_device}}`) — `name`=`ovpn-srv`, `port`={{port}}
+or (443 for camouflage / 1194 default), `protocol`={{protocol}} or tcp,
+`mode`={{mode}} or ip, `certificate`=<server cert>, `require_client_certificate=true`,
+`auth=sha256`, `cipher=aes256-gcm,aes256-cbc`, `tls_version=only-1.2`,
+`default_profile`=the profile, `enabled` (or `enable_ovpn_server`). Strong cipher +
+TLS 1.2 both hardens and looks like modern HTTPS.
+
+## 5. Client (client side)
+
+`create_ovpn_client` (`device={{client_device}}`) — `name`=`ovpn-{{server_device}}`,
+`connect_to`=server public IP/DDNS, `port`={{port}} or match, `protocol`=match,
+`mode`=match, `user`/`password`=the PPP secret, `certificate`=<client cert>,
+`verify_server_certificate=true`, `cipher`/`auth`/`tls_version` matching the server.
+Use `route_nopull=true` if you want to control routing manually (recommended for
+site-to-site), else the server can push routes.
+
+## 6. Route (mode=ip) or bridge (mode=ethernet)
+
+- **mode=ip:** transit link is up once connected; `add_route` far LAN on each side
+  (server→client-LAN, client→server-LAN) via the tunnel interface / transit IP. Or
+  push routes from the server profile.
+- **mode=ethernet:** add the OVPN interface as a **bridge port** on each side's LAN
+  bridge (one L2 domain) — enable STP, single DHCP authority, watch MTU.
+
+## 7. Firewall — safely
+
+Under Safe Mode per device: server `input` accept `protocol={{protocol}} (tcp)
+dst-port={{port}}` (443/1194) from the client's source (any if dynamic), high in the
+chain; both sides `forward` allow the two LANs.
+
+## 8. MTU / MSS
+
+OpenVPN adds notable overhead; TCP mode risks TCP-in-TCP stalls. Set the client
+`max_mtu` conservatively (~1400), clamp MSS on `forward`. UDP mode is faster where
+it isn't blocked; TCP/443 is for reachability.
+
+## 9. Verify
+
+- Server: `list_ovpn_servers`/`get_ovpn_server` running; the client appears as a
+  connected session. Client: `get_ovpn_client` status `connected`, address assigned.
+- `ping` (`device=server`) client tunnel/LAN (with `src_address`=server-LAN), repeat
+  from client. For `mode=ethernet`, prove same-subnet L2 reachability + DHCP. Large-
+  payload ping to confirm MTU.
+
+## Bypassing country / DPI restrictions (legitimate circumvention)
+
+Lawful privacy/accessibility only; comply with local law and terms. OpenVPN on
+**TCP 443** presents a TLS session on the HTTPS port — a strong native bypass with a
+**different fingerprint from SSTP**, so it's the natural second option if SSTP is
+blocked. Maximize blend-in: `protocol=tcp`, `port=443`, `tls_version=only-1.2`, AES-
+GCM, valid-looking cert. Note: classic OpenVPN has a recognizable TLS handshake that
+sophisticated DPI (active probing / TLS-fingerprint allow-lists) can still flag —
+if that's the adversary, escalate to **container-based obfuscation** (XRay/VLESS+
+Reality, sing-box, Shadowsocks, obfs4) in a RouterOS `/container` or a VPS (not
+native, heaviest, most robust), or run WireGuard _inside_ this OpenVPN link. Compare
+with `setup-sstp-tunnel-between-sites` and pick the transport the local DPI doesn't
+recognize. Never present obfuscation as a guarantee — it's an arms race.
+
+---
+
+Report: certs used, PPP profile/secret, server + client settings (mode/protocol/port),
+routing or bridging, firewall added, MTU/MSS, verification results. State which device
+each change ran on. Never apply changes the user hasn't approved.

package/prompts/setup-sstp-tunnel-between-sites.md

@@ -0,0 +1,136 @@
+---
+name: setup-sstp-tunnel-between-sites
+title: Build an SSTP (TLS/443) tunnel between two MikroTik devices
+description: Configure a MikroTik-to-MikroTik SSTP site-to-site link — server certificate, PPP profile + secret, client, routing, firewall — over TCP 443 so it looks like HTTPS. The go-to transport for bypassing VPN blocks / DPI. Verified end to end.
+arguments:
+  - name: server_device
+    description: The device that will run the SSTP SERVER — the one with a reachable public IP / DDNS and (ideally) a certificate. Config key or label from list_mikrotik_devices.
+    required: false
+  - name: client_device
+    description: The device that will run the SSTP CLIENT (may be behind NAT). Config key or label.
+    required: false
+  - name: tunnel_subnet
+    description: Transit subnet for the PPP link, e.g. 10.255.255.0/30 (server=.1 local, client=.2 remote). Omit to let you pick one that collides with neither LAN.
+    required: false
+  - name: port
+    description: TCP port for SSTP. Default and recommended 443 (looks like HTTPS, survives most DPI). Omit for 443.
+    required: false
+---
+
+You are building an **SSTP site-to-site tunnel between two MikroTik routers**. SSTP
+is **PPP inside TLS over TCP (default 443)** — on the wire it is nearly
+indistinguishable from an HTTPS session, which makes it the **best native RouterOS
+choice for bypassing VPN blocks and DPI**. It is client↔server (asymmetric): one
+device is the **server** (needs a reachable endpoint + a TLS certificate), the other
+is the **client** (can be behind NAT). Drive both via the `device` argument. This
+touches certificates, PPP, and the firewall — go carefully and confirm before writing.
+
+Server device: {{server_device}}
+Client device: {{client_device}}
+Transit subnet: {{tunnel_subnet}}
+Port: {{port}}
+
+## 0. Discover and assign roles (FIRST)
+
+- `list_mikrotik_devices`; resolve {{server_device}}/{{client_device}} — never
+  substitute a similar name; ask which is which if omitted.
+- The **server** must be reachable on the chosen TCP `port` (static WAN or DDNS via
+  `/ip cloud`). The **client** only needs outbound TCP to that port — NAT-friendly.
+  Confirm roles with the user before proceeding.
+
+## 1. Facts (read-only, per device)
+
+Per side (`device=<name>`): `get_system_identity`, `list_ip_addresses`,
+`get_routing_table`, `get_ip_cloud`, and on the server `list_certificates`. Record
+the server's public address/DDNS, each LAN subnet (must not overlap), and whether a
+usable server certificate already exists.
+
+## 2. Server certificate (server side)
+
+SSTP requires a TLS certificate on the server. If none exists:
+
+- `create_certificate` a local CA, then `create_certificate` a server cert (common-
+  name = the server's public IP/DDNS the client will connect to), `sign_certificate`
+  both (CA self-signed, server signed by the CA). Note the server cert name.
+- The client should trust that CA: either `import_certificate` the CA on the client,
+  or set the client's `verify_server_certificate=false` (simpler, but skips
+  authenticity — acceptable only if the PSK-like PPP credentials are strong; state
+  the trade-off). A publicly-trusted (Let's Encrypt) cert avoids this — see
+  `manage-certificates`.
+
+## 3. PPP profile + secret (server side)
+
+- `create_ppp_profile` — set `local-address`=server transit IP (e.g. `10.255.255.1`),
+  `remote-address`=client transit IP (e.g. `10.255.255.2`) or a small pool. Optionally
+  set DNS. This profile defines the tunnel's L3 endpoints.
+- `create_ppp_secret` — `name`/`password` (strong), `service=sstp`, `profile`=the
+  profile above. These are the client's login credentials.
+
+## 4. Enable the SSTP server (server side)
+
+`set_sstp_server` (`device={{server_device}}`) — `enabled=true`,
+`certificate`=<server cert>, `port`={{port}} or 443, `default_profile`=the profile,
+`authentication=mschap2` (drop weaker methods), `tls_version=only-1.2`, `pfs=true`,
+`force_aes=true`. Strong ciphers + TLS 1.2-only both hardens and makes the flow look
+like modern HTTPS.
+
+## 5. Client (client side)
+
+`create_sstp_client` (`device={{client_device}}`) — `name`=`sstp-{{server_device}}`,
+`connect_to`/server address = the server's public IP/DDNS, `port`={{port}} or 443,
+`user`/`password` = the PPP secret from step 3, `verify_server_certificate` per step 2,
+`tls_version=only-1.2`, `pfs=true`, `authentication=mschap2`. The client auto-creates
+the PPP interface and gets the transit `remote-address`.
+
+## 6. Route each far LAN
+
+The transit /30 is connected once the PPP link is up. Add routes for the far LANs:
+
+- On the server: `add_route` dst=client-LAN gw=the client's transit IP (or the
+  dynamic SSTP interface).
+- On the client: `add_route` dst=server-LAN gw=the server's transit IP (or the SSTP
+  interface). Or push routes via the PPP profile.
+
+## 7. Firewall — safely
+
+Under Safe Mode per device (`enable_safe_mode`→edits→verify→`commit_safe_mode`):
+
+- Server `input`: accept `protocol=tcp dst-port={{port}}` (443) from anywhere the
+  client may source from (dynamic clients ⇒ from any), placed above any default drop.
+- Both sides `forward`: allow the two LANs both directions.
+
+## 8. MTU / MSS
+
+SSTP over TCP/TLS adds overhead and is prone to TCP-in-TCP meltdown on lossy links.
+Set the client `max_mtu`/`max_mru` conservatively (~1400) and clamp MSS on `forward`.
+Prefer this transport for _reachability_, not raw throughput.
+
+## 9. Verify
+
+- Server: `get_sstp_server` enabled; check active PPP (the client should appear as a
+  connected session). Client: `get_sstp_client` — status `connected`, transit IP
+  assigned.
+- `ping` (`device=server`) the client transit IP then a client-LAN host with
+  `src_address`=server-LAN IP; repeat from the client. `traceroute` if a path is off.
+
+## Why this is the bypass workhorse (legitimate circumvention)
+
+Lawful privacy/accessibility only; comply with local law and terms. SSTP on TCP 443
+**is** the DPI-bypass technique for native RouterOS — it presents as a standard TLS
+session to a common HTTPS port, so it passes most "block VPN protocols" filters that
+stop WireGuard/IKE/GRE. To maximize blend-in: keep `port=443`, `tls_version=only-1.2`,
+strong AES + PFS, and a certificate with a plausible CN. If SSTP itself is
+fingerprinted/blocked (active probing, TLS-fingerprint allow-lists), escalate to:
+**OpenVPN TCP/443** (`setup-openvpn-tunnel-between-sites`) for a different TLS
+signature, or **container-based obfuscation** (XRay/VLESS+Reality, sing-box,
+Shadowsocks, obfs4) run in a RouterOS `/container` or a VPS — not native, heaviest,
+most robust. You can also run WireGuard _inside_ this SSTP link so the WG handshake
+never touches the open internet. Never present obfuscation as a guarantee — it's an
+arms race.
+
+---
+
+Report: server cert used, PPP profile/secret, server settings, client status, routes
+
+- firewall added, MTU/MSS, verification results. State which device each change ran
+  on. Never apply changes the user hasn't approved.

package/prompts/setup-tunnel-between-sites.md

@@ -4,19 +4,29 @@ title: Build a tunnel between two MikroTik devices
 description: Configure BOTH routers of a site-to-site tunnel from one conversation, then verify it end to end.
 arguments:
   - name: device_a
-    description: Name of the first configured device (see list_mikrotik_devices), e.g. site-a.
-    required: true
+    description: First configured device (config key or label from list_mikrotik_devices), e.g. site-a. Omit to discover and choose.
+    required: false
   - name: device_b
-    description: Name of the second configured device, e.g. site-b.
-    required: true
+    description: Second configured device, e.g. site-b. Omit to discover and choose.
+    required: false
   - name: technology
-    description: Tunnel type to use — wireguard, ipsec, gre, eoip, or "recommend" to let you choose.
+    description: Tunnel type — wireguard, ipsec, gre, ipip, eoip, vxlan, sstp, ovpn, or "recommend" to let you choose. For a deep, tech-specific walkthrough use setup-wireguard-tunnel-between-sites or setup-gre-tunnel-between-sites.
     required: false
 ---
 
 You are configuring a **site-to-site tunnel between two MikroTik routers** that
 this server can both reach. You will drive BOTH devices in one flow by passing
-the `device` argument on each tool call.
+the `device` argument on each tool call. This is the general chooser-and-builder;
+for a detailed, tech-specific flow prefer the dedicated per-technology prompts,
+which cover keys/certs, MTU/MSS, and DPI-bypass transports in depth:
+**`setup-wireguard-tunnel-between-sites`** (WireGuard),
+**`setup-gre-tunnel-between-sites`** (GRE + IPsec),
+**`setup-ipip-tunnel-between-sites`** (IP-in-IP),
+**`setup-eoip-tunnel-between-sites`** (L2 bridgeable),
+**`setup-vxlan-tunnel-between-sites`** (L2 overlay / multipoint),
+**`setup-ipsec-site-to-site`** (IKEv2 policy-based),
+**`setup-sstp-tunnel-between-sites`** and
+**`setup-openvpn-tunnel-between-sites`** (TLS/443 — the bypass workhorses).
 
 Device A: {{device_a}}
 Device B: {{device_b}}
@@ -24,6 +34,13 @@ Requested technology: {{technology}}
 
 Work in this order, confirming the plan before any change:
 
+0. **Discover both endpoints.** Call `list_mikrotik_devices` first and resolve
+   {{device_a}} / {{device_b}} against it — never substitute a similar name (these
+   are different physical routers). If either was omitted, ask which two devices to
+   connect. Note which side (if any) has a reachable public endpoint vs. is behind
+   NAT — if **both** are behind NAT with no forward, a direct tunnel can't form
+   (use a reachable side or a relay/VPS).
+
 1. **Inventory both ends.** Call `list_mikrotik_devices` first. Then, for each of
    {{device_a}} and {{device_b}}, gather facts with `device=<name>`:
    `get_system_identity`, `list_interfaces`, `list_ip_addresses`,
@@ -48,10 +65,40 @@ Work in this order, confirming the plan before any change:
    (`device=<name>`) per device before firewall edits, verify, then
    `commit_safe_mode` — Safe Mode is tracked per device, so each router commits
    independently.
-5. **Verify end to end.** From {{device_a}} run `ping` (`device={{device_a}}`) to
+5. **MTU / MSS.** Every tunnel shrinks the usable MTU (WireGuard ~60 B, GRE 24 B,
+   GRE+IPsec ~70+ B), so small pings pass but large TLS/file flows stall. Set the
+   tunnel interface MTU accordingly (WG 1420, GRE 1476, lower on PPPoE / when also
+   IPsec-wrapped) and clamp TCP MSS (`clamp-tcp-mss` on the tunnel, or a `forward`
+   mangle `change-mss new-mss=clamp-to-pmtu tcp-flags=syn`). Confirm non-overlapping
+   LANs before routing — overlap makes the far route ambiguous.
+6. **Verify end to end.** From {{device_a}} run `ping` (`device={{device_a}}`) to
    the far tunnel address and a host in B's LAN (set `src_address` to A's LAN IP);
    repeat from {{device_b}}. For IPsec, check `get_ipsec_active_peers` on both.
-   Use `traceroute` if a path is wrong.
+   Test a large payload (ping size 1400, do-not-fragment) to catch MTU issues. Use
+   `traceroute` if a path is wrong.
+
+## Bypassing country / DPI restrictions (legitimate censorship circumvention)
+
+For lawful privacy / accessibility on networks you're authorized to use — comply
+with local law and service terms. Escalate only as far as the block requires:
+
+- **Port camouflage** — run the encrypted tunnel on a rarely-filtered port (UDP/443
+  for WireGuard, UDP 4500 for IPsec NAT-T). Cheapest; hides the port, not the
+  handshake.
+- **TLS-looking transport** — where DPI fingerprints WireGuard/IKE, wrap the routed
+  tunnel in **SSTP** (PPP-over-TLS, TCP 443 — looks like HTTPS) or **OpenVPN TCP/443**
+  (`create_sstp_client` / `create_ovpn_client`) and route the far LANs over that, or
+  run WG/GRE inside it. Trades throughput for reachability.
+- **Alternate fingerprint** — if one protocol is specifically blocked, switch: WG↔
+  IKEv2↔SSTP present different signatures on the wire.
+- **Container-based obfuscation (advanced)** — the strongest anti-DPI tools
+  (XRay/VLESS+Reality, sing-box, Shadowsocks, obfs4) are **not native** to RouterOS;
+  run one in a **`/container`** or on a VPS you control and route the site tunnel
+  through it. Confirm container support and spare resources first.
+
+Recommend the lightest option that works; never present obfuscation as a guarantee.
+The dedicated `setup-wireguard-tunnel-between-sites` and
+`setup-gre-tunnel-between-sites` prompts cover these transports in more depth.
 
 Report the tunnel parameters used on each side, the verification results, and any
 follow-ups (e.g. routes still needed). Never apply changes the user hasn't approved.

package/prompts/setup-v2ray-container-proxy.md

@@ -0,0 +1,203 @@
+---
+name: setup-v2ray-container-proxy
+title: Run V2Ray/Xray (VLESS·Reality·VMess·Trojan·Shadowsocks) in a MikroTik container and route traffic through it
+description: Deploy an Xray / V2Ray / sing-box client inside a RouterOS /container, wire its VETH into the router, and selectively (or fully) route LAN traffic through the encrypted VLESS-Reality / VMess / Trojan / Shadowsocks / Hysteria tunnel — with device-mode, disk, MTU, DNS-leak and kill-switch handling. For lawful privacy / censorship circumvention on networks you are authorized to use.
+arguments:
+  - name: device
+    description: Which configured MikroTik to run the proxy container on (config key or label from list_mikrotik_devices). Omit to discover and choose.
+    required: false
+  - name: protocol
+    description: V2Ray-family protocol the tunnel will use — vless-reality (recommended), vless-vision, vmess, trojan, shadowsocks, or (sing-box) hysteria2/tuic. This is configured INSIDE the container image, not on RouterOS.
+    required: false
+  - name: image
+    description: Container image to run (e.g. gritsenko/xray-mikrotik:latest, or a sing-box image). Omit to let you recommend one matching the device architecture and chosen protocol.
+    required: false
+  - name: scope
+    description: What to route through the tunnel — "selective" (only domains/IPs on an address-list, default and recommended) or "all" (default route via the tunnel, with a kill-switch).
+    required: false
+---
+
+You are deploying a **V2Ray / Xray-core (or sing-box) client inside a MikroTik
+RouterOS `/container`** and routing LAN traffic through its encrypted tunnel. This
+is the _native-RouterOS_ way to run the modern censorship-resistant protocols —
+**VLESS (+Vision/XTLS), VLESS + Reality, VMess, Trojan, Shadowsocks**, and (with a
+sing-box image) **Hysteria2 / TUIC** — that RouterOS has no built-in support for.
+The router runs the client; a remote V2Ray/Xray **server (a VPS you control)** is
+the other end. This flow configures the RouterOS side; the tunnel's crypto
+parameters live in the container image's config/env.
+
+**Legality & scope.** This is for **lawful privacy and accessibility** on networks
+and services you are authorized to use — comply with local law and provider terms.
+Confirm the user understands this before proceeding. Treat the remote server
+address, UUIDs, keys and short-ids as **secrets** — never log or echo them back in
+full; mask them in your reports.
+
+Target device: {{device}}
+Protocol: {{protocol}}
+Image: {{image}}
+Routing scope: {{scope}}
+
+---
+
+## 0. Discover the device and confirm it CAN run containers (do this FIRST)
+
+- Call `list_mikrotik_devices`; resolve `{{device}}` (never substitute a similar
+  name). If omitted, present the inventory and ask which router. Pass `device=` on
+  every subsequent call.
+- **Prerequisite check (read-only)** — containers have hard requirements; verify all
+  before proposing changes:
+  - `get_system_resources` (`device=<name>`) — confirm **architecture** is `arm`,
+    `arm64`, or `x86` (**MIPS/SMIPS cannot run containers** — stop and say so), and
+    that there is spare **RAM/CPU**.
+  - `list_containers` — if it errors, the **`container` package isn't installed**.
+  - Confirm an **external disk** (USB/NVMe, ext4) exists for the container root-dir —
+    running container images off internal flash wears it out fast. Check with
+    `run_routeros_command` `/disk print`.
+- **Two prerequisites need out-of-band action — flag, do NOT silently attempt:**
+  1. **device-mode = container=yes.** Enabling it (`/system/device-mode/update
+mode=advanced container=yes`) requires **physical confirmation** (press the
+     reset button or power-cycle within the timeout). You cannot complete this
+     remotely — tell the user they must do the physical step.
+  2. **Installing the `container` package** requires uploading the `.npk` and
+     `/system/package/apply-changes` (7.18+) which **reboots** the router. Get
+     explicit approval; note the device will drop offline during reboot.
+
+  Do not proceed to container creation until architecture, disk, package, and
+  device-mode are all satisfied.
+
+## 1. Choose image and protocol
+
+- **Protocol** (`{{protocol}}`): recommend **VLESS + Reality** as the default —
+  Reality forges the TLS handshake of a real public site (no certificate to obtain,
+  no domain to burn, strongest anti-DPI of the family). VLESS+Vision/XTLS, VMess,
+  Trojan, and Shadowsocks are alternatives; sing-box images add Hysteria2/TUIC
+  (QUIC-based, good on lossy/throttled links). The choice is realised in the
+  container's config — RouterOS just carries the encapsulated traffic.
+- **Image** (`{{image}}`): pick one matching the device architecture (map:
+  `arm→linux/arm/v7`, `arm64→linux/arm64`, `x86→linux/amd64`). Community images
+  (e.g. `gritsenko/xray-mikrotik`) bundle **xray-core + tun2socks** so the
+  container's VETH acts directly as a routable gateway — simplest. Otherwise the
+  **two-container** pattern (below) is the general form. **Read the specific image's
+  README for its exact env-var names** — they differ per image; do not assume.
+- **RouterOS local-import caveat:** `add_container remote_image=` pulls from a
+  registry (needs `set_container_config registry-url=... tmpdir=disk1/pull` and
+  internet). A local `.tar` must be **single-layer, uncompressed, Docker-v1** — most
+  people pull from a registry.
+
+## 2. Two deployment shapes (pick one, explain to the user)
+
+**A — All-in-one image (recommended, simplest).** One container running xray-core +
+tun2socks. Its VETH IP becomes the gateway you route through. Example env schema
+(gritsenko/xray-mikrotik — verify against the image):
+`SERVER_ADDRESS`, `SERVER_PORT`, `USER_ID`, `ENCRYPTION`, `FINGERPRINT_FP`,
+`SERVER_NAME_SNI`, `PUBLIC_KEY_PBK`, `SHORT_ID_SID`.
+
+**B — Two-container (general, more control).** Container 1 = xray-core exposing a
+**SOCKS5** inbound (e.g. `172.17.0.2:1080`); Container 2 = **tun2socks /
+hev-socks5-tunnel** turning that SOCKS5 into a routable gateway on its own VETH.
+Typical env — xray: `REMOTE_ADDRESS,REMOTE_PORT,ID,FLOW,PUBLIC_KEY,SHORT_ID,
+SERVER_NAME`; tun: `SOCKS5_ADDR=172.17.0.2,SOCKS5_PORT=1080,LOCAL_ROUTE` (so LAN
+subnets return via the router, not the tunnel). _Note: original tun2socks has arm64
+issues — use an arm64-built image._
+
+## 3. Container networking (VETH + NAT + DNS)
+
+There is **no dedicated VETH tool** — create it with `run_routeros_command`
+(approve each raw command). Example for shape A on a /30:
+
+- `/interface veth add name=veth-xray address=172.18.20.6/30 gateway=172.18.20.5`
+- `add_ip_address` `address=172.18.20.5/30 interface=veth-xray` (router side).
+- `create_nat_rule` `chain=srcnat action=masquerade out-interface=veth-xray` (so the
+  container reaches the internet / the remote server).
+- Container `dns` = the router's veth IP (`172.18.20.5`) or a resolver you trust.
+  (Shape B: put both VETHs on a `containers` bridge, `172.17.0.1/24` gateway.)
+
+## 4. Create and start the container
+
+- If pulling from a registry: `set_container_config` `registry-url=https://registry-1.docker.io tmpdir=disk1/pull`.
+- Env vars: either inline via `add_container` `env="SERVER_ADDRESS=...,USER_ID=..."`
+  (7.21+) or as a named list with `add_container_env` (`envlists=`). **Mask the
+  secret values in anything you print back.**
+- `add_container` (`device=<name>`) — `remote_image={{image}}`, `interface=veth-xray`,
+  `root_dir=disk1/xray`, `dns=172.18.20.5`, `logging=yes`, `start_on_boot=yes`,
+  `hostname=xray`, and the env.
+- `start_container`; then `get_container` / `list_containers` until it shows
+  **running**, and read startup output with the container-log (it must show a
+  successful outbound handshake to your server before routing anything through it).
+
+## 5. Route traffic through the tunnel
+
+**Selective (`scope=selective`, recommended)** — only chosen destinations go through
+the proxy; everything else uses the normal WAN (fast, low-risk, defeats geo-blocks
+for the sites that need it):
+
+1. `add_address_list_entry` — build a list `via_proxy` of the domains/IPs to tunnel
+   (RouterOS resolves domain entries to IPs automatically).
+2. `add_routing_table` — `name=proxy fib`.
+3. `create_mangle_rule` — `chain=prerouting action=mark-routing
+new-routing-mark=proxy dst-address-list=via_proxy passthrough=no`
+   (add `src-address=<LAN>` to scope to LAN clients; exclude the router's own/ the
+   container subnet to avoid loops).
+4. `add_route` — `dst-address=0.0.0.0/0 gateway=172.18.20.6 routing-table=proxy`
+   (gateway = the container's VETH IP, shape A; the tun container's IP, shape B).
+
+**All traffic (`scope=all`)** — default route via the tunnel. Same routing table but
+mark all LAN traffic (or set the container gateway as the main default). **Mandatory
+kill-switch:** add a low-priority `forward` **drop** for the LAN when the tunnel
+interface is down, so a container crash can't silently leak traffic out the clear
+WAN. Also pin a **higher-priority route to the remote server's IP via the real WAN**
+so the tunnel's own packets don't recurse into itself.
+
+## 6. DNS-leak & MTU handling
+
+- **DNS leaks:** if clients query a public resolver directly, the destination is
+  exposed even though the payload is tunnelled. Redirect LAN DNS (dst-nat UDP/TCP 53
+  to the router or the container's resolver) so lookups for proxied domains resolve
+  through the tunnel, or run the resolver inside/behind the container.
+- **MTU/MSS:** encapsulation shrinks usable MTU — add a `create_mangle_rule`
+  `chain=forward action=change-mss new-mss=clamp-to-pmtu tcp-flags=syn` (and/or lower
+  the veth MTU). This is the #1 "handshake works, big pages hang" cause.
+
+## 7. Firewall — safely
+
+Under Safe Mode (`enable_safe_mode` `device=<name>` → edits → verify →
+`commit_safe_mode`): allow the container subnet outbound, keep the masquerade from
+step 3, and (scope=all) install the kill-switch drop. Do not expose the container's
+SOCKS5 port to the WAN.
+
+## 8. Verify end to end
+
+- `get_container` shows **running**; the container log shows a completed handshake to
+  your server (no repeated dial errors).
+- From a **marked** LAN source, check the **egress IP** changed: fetch an "what is my
+  IP" service from a proxied client (or `run_routeros_command` a `/tool fetch` bound
+  to the proxy path) — it should show the **VPS** IP, not the local WAN IP.
+- Confirm a **non-proxied** destination still exits the normal WAN (selective scope).
+- `ping`/`traceroute` a proxied target; test a large HTTPS page (MTU sanity).
+- Reboot-persistence: `start_on_boot=yes` and the routing rules survive a reboot.
+
+## 9. Family notes, hardening & honest caveats
+
+- **VLESS + Reality**: no cert/domain needed; set a believable `SERVER_NAME_SNI`
+  (a real, unrelated HTTPS site the censor won't block) and matching public-key/
+  short-id from the server. Strongest default against active-probing DPI.
+- **VMess/Trojan/Shadowsocks**: pair with TLS/WebSocket/gRPC transports on 443 for
+  camouflage; plain Shadowsocks is weaker against modern DPI.
+- **Hysteria2/TUIC** (sing-box image): QUIC/UDP — great on lossy or throttled links,
+  but blocked where UDP is throttled.
+- **Trust**: you are running a third-party image with your keys and all your traffic.
+  Prefer images you can inspect/build; pin a digest; keep it updated.
+- **Reality/DPI is an arms race** — never present it as a guarantee. Keep a fallback
+  (a second protocol/port, or an SSTP/OpenVPN-443 transport per
+  `setup-sstp-tunnel-between-sites`).
+- **Resource reality**: containers are RAM/CPU/disk heavy on small routers; on very
+  low-end boards run the client on a VPS/box and point the router at it instead.
+
+---
+
+Report: device, architecture, image + protocol, VETH/NAT, container status, the
+routing-table + mangle + route rules and the address-list scope, DNS/MTU/kill-switch
+handling, and the verification results (egress-IP proof) — with **all secrets
+masked**, and a note of every `run_routeros_command` step used (VETH, device-mode).
+Flag the physical device-mode step and any reboot explicitly. Never apply changes the
+user hasn't approved.