========================================================================
 SubnetSlinger — System Requirements & Setup
 The modern network engineer's desktop toolkit (Windows · Linux · macOS)
========================================================================

SubnetSlinger runs LOCALLY on your workstation — the core diagnostics need
no internet and no account. This file lists what it takes to run it well,
the administrator rights and dependencies for the optional features, and the
network ports the built-in test servers use. Requirements differ by OS; the
per-OS notes below call out the differences.


------------------------------------------------------------------------
 1. SUPPORTED OPERATING SYSTEMS
------------------------------------------------------------------------
  Windows   Windows 10 (build 1809 / version 1809 or later) or Windows 11,
            64-bit (x64). Installed as an MSIX package.
  Linux     64-bit (x64), a modern glibc desktop — e.g. Ubuntu 20.04+,
            Debian 11+, Fedora 38+. X11 or Wayland. Ships self-contained
            (its own .NET runtime) — nothing to pre-install.
  macOS     macOS 14 (Sonoma) or later. (Separate native build.)

  The app bundles its own runtime on every OS — you do NOT install .NET,
  Mono, or any framework separately.

  Also: a 1280x800 or larger display. The FREE tier needs no account and no
  internet. Unlocking PRO is a one-time online sign-in with a free account;
  after that everything runs locally — only cloud AI and the internet tools
  (speed test, WHOIS, public IP) need ongoing internet. GPU acceleration for a
  local Ollama model needs current GPU drivers (NVIDIA/AMD) or Apple Silicon.


------------------------------------------------------------------------
 2. WORKSTATION SPECS  (minimum vs recommended)
------------------------------------------------------------------------
  The app itself is light — the MINIMUM runs every tool with cloud AI or no
  AI. The RECOMMENDED spec is for comfortable daily use and headroom for the
  one feature that really wants a bigger machine: running the AI LOCALLY
  (Ollama).

  AI & YOUR SPEC — it depends on WHERE the model runs, not just whether you
  use AI. The heavy spec lives wherever the model actually runs; your
  workstation only needs it when the model runs ON the workstation:

    How you run the AI            Workstation needs     Heavy spec lives on
    ---------------------------   -------------------   --------------------
    No AI                         Minimum               —
    Cloud AI (your own key)       Minimum + internet    the AI provider
    Your own inference server     Minimum + reach it    that server/platform
      (remote Ollama, OR any
       OpenAI-compatible endpoint:
       vLLM, LM Studio, Azure
       OpenAI, enterprise serving)
    Local Ollama (this box)       32 GB + GPU           this workstation

  So cloud AI AND any inference you host elsewhere (a shared Ollama box or an
  OpenAI-compatible endpoint on your own infrastructure) both keep the
  workstation at the MINIMUM — only running the model locally on the box
  raises its spec.

                    MINIMUM                    RECOMMENDED
    CPU             64-bit dual-core           64-bit quad-core or better
    RAM             8 GB                       16 GB  (32 GB for local AI)
    Disk            ~500 MB free               SSD, 2 GB+ free
    GPU             none (integrated OK)       for local AI: 8 GB+ VRAM or
                                               Apple Silicon (else not needed)
    Network         LAN for diagnostics;       same
                    internet for cloud AI,
                    speed test, WHOIS,
                    public-IP lookups

  RUNNING THE AI LOCALLY (Ollama — optional, free, fully private)
    RAM     32 GB or more to run a model properly. A small 7-8B model is the
            practical floor; a Posse sweep is ~6 model passes back to back,
            so headroom matters. Below ~32 GB expect heavy swapping and slow
            answers, and larger/again-better models want even more.
    GPU     Strongly recommended — 8 GB+ VRAM (NVIDIA/AMD) or Apple Silicon.
            CPU-only works but is slow.
    Disk    +5-10 GB per local model you pull.
    Note    Cloud AI (Anthropic/OpenAI/Gemini with your own key) needs NONE
            of this — just internet and a key. The minimum spec is fine.

  SHARED / REMOTE OLLAMA (point at a server, not the workstation)
    You do NOT have to run Ollama on the workstation. In the Deputy's Ollama
    settings, set the host to any reachable server — e.g. http://ollama.lan:11434
    — and BOTH the Deputy and the Posse use it. Ideal for teams: stand up ONE
    32 GB + GPU box on the network, and every engineer's workstation runs at
    the MINIMUM spec — free, private, no per-seat GPU. The "for local AI" specs
    above then apply to the SERVER, not each workstation.
      Server side: Ollama must listen on the network (OLLAMA_HOST=0.0.0.0:11434)
      and its port must be reachable through the firewall; the server pulls the
      models. The workstation just needs to reach it over the LAN.
      Privacy: the host is on YOUR network, so prompts stay inside your own
      trust boundary (not a third-party cloud). Secrets are masked before the
      model anyway (see below), so nothing sensitive reaches that server either.
    Beyond Ollama: the OpenAI-compatible backend points at ANY endpoint that
    speaks the OpenAI API — self-hosted vLLM/LM Studio, Azure OpenAI, or an
    enterprise model-serving platform (e.g. a Databricks serving endpoint) —
    set the base URL, key, and model in the Deputy. Same spec benefit: the
    inference runs on that server.

  SECRET REDACTION (every backend, on by default)
    Known secret and device-config patterns (device passwords, SNMP/TACACS+/
    RADIUS keys, private keys, API tokens, etc.) are masked in the copy sent to
    the model — cloud provider, OpenAI-compatible endpoint, or local/remote
    Ollama, all treated the same. It is pattern-based: a strong safety net, not
    an absolute guarantee — an unlabeled secret with no recognizable shape can
    still slip through. You still see the real values in the transcript; only
    the model's copy is scrubbed, so recognized secrets don't reach the model
    or a saved transcript / incident / export. Credential-specific work (Cisco
    Type-7 decode, etc.) stays in the Security tool, on your machine.

  WHY THESE NUMBERS (the local-AI math)
    - The app itself is small: a self-contained .NET/Avalonia build, ~130 MB
      on disk and a few hundred MB of RAM in use. It is NOT what drives the
      spec — a local model is. The toolkit itself runs in a few hundred MB;
      8 GB is set as a realistic floor for a professional workstation, and
      everything above that is headroom for Ollama.
    - A local model needs roughly its FILE SIZE held in memory, PLUS a few GB
      for the conversation's context (the KV cache), PLUS the OS and the app.
      Ollama models at the common Q4 quantization run about:
          7-8B  model  ~ 5 GB      (llama3.1:8b, qwen2.5:7b)
          13-14B model ~ 9 GB      (qwen2.5:14b)
          32B   model  ~ 20 GB     (qwen2.5:32b)
          70B   model  ~ 40 GB     (llama3.1:70b)
    - So 8 GB total only fits a small model with little else running; 16 GB
      makes an 8B model comfortable; 32 GB gives room for a genuinely capable
      14-32B model, longer network context, AND a Posse sweep (which keeps the
      model loaded across ~6 back-to-back passes) — without swapping to disk.
    - GPU: Ollama offloads the model to VRAM and runs many times faster than
      CPU-only. Fit an 8B model in ~6-8 GB VRAM, a 14B in ~10 GB. Apple Silicon
      shares system RAM as GPU memory, so its 32 GB does double duty.
    - Disk: each model file is one of the sizes above (4-40 GB), which is why
      local AI adds 5-10 GB for a typical 7-14B model.
    - Cloud AI moves ALL of that compute to the provider — your machine just
      sends a request — so the MINIMUM spec runs the Deputy and Posse fine. See the in-app AI cost help.


------------------------------------------------------------------------
 3. ADMINISTRATOR RIGHTS & FIRST-RUN SETUP  (differs by OS)
------------------------------------------------------------------------
  You do NOT need to be an administrator for everyday use. Admin rights are
  needed only for a few OS-level grants, once:

  WINDOWS
    - Install: standard user can install the signed MSIX.
    - Firewall: the installer adds inbound rules for the local test servers
      automatically (scoped to the app, Private profile only — see section 5).
      No runtime prompt. If you run a server on a CUSTOM or fallback port,
      use the in-app "Add firewall rules" button (that one elevation prompt).
    - Npcap (only if you use the Capture tool): the driver install requires
      administrator rights — see section 4.
    - OpenSSH Server (only for SFTP/SCP "receive"): enabling the Windows
      optional feature requires administrator rights — see section 4.

  LINUX
    - Live packet Capture is the ONLY feature that needs a capability grant.
      Grant it ONCE with the bundled installer:
          sudo ./install-linux.sh        (prompts for admin via pkexec/sudo)
      It runs: setcap 'cap_net_raw,cap_net_admin+ep' on the tiny capture
      helper (subnetslinger-capd) — NEVER on the app itself. The GUI stays a
      normal unprivileged process (Wireshark/dumpcap model), so its Save /
      Export / Import file dialogs keep working and its in-memory Vault key
      can't be ptraced or captured in a core dump. The in-app "Grant
      permission" button does the same thing.
    - Ping / Traceroute need NO grant — they fall back to the system `ping`.
    - Local servers need NO grant — every privileged port (Syslog 514, TFTP
      69, DNS 53, TACACS+ 49, FTP 21, HTTP 80, SNMP-trap 162) offers a
      high-port fallback the panel selects when a low bind is refused.
    - Serial console: add your user to the `dialout` group (log out/in) to
      open /dev/ttyUSB*.
    - Capture needs libpcap (usually preinstalled) — see section 4.

  macOS
    - Packet capture uses the BPF devices; the standard ChmodBPF helper (as on
      Wireshark) grants access. Details ship with the macOS build.


------------------------------------------------------------------------
 4. OPTIONAL DEPENDENCIES (install only for the feature you use)
------------------------------------------------------------------------
  CAPTURE (live packet analyzer)
    Windows : Npcap  (npcap.com) — install with "WinPcap API-compatible mode".
              Admin required. It's a kernel driver, so it cannot ship inside
              the app; the app detects a missing driver and tells you.
    Linux   : libpcap (net-tools/libpcap — usually already present).
    macOS   : built in.

  CLI TOOLS YOU DRIVE (the "CLI wrappers" tool)
    SubnetSlinger does NOT bundle these — the tool builds the command and runs the
    one you already have installed. Install only the ones you'll use:
      Linux   : sudo apt install nmap curl bind9-dnsutils mtr tcpdump  (or dnf/pacman)
      Windows : nmap (nmap.org); curl/dig via built-ins or your package manager.
    The form tells you at runtime if the underlying tool isn't on PATH.

  SFTP / SCP "RECEIVE" (Local servers)
    Windows : OpenSSH Server optional feature, then start the service (admin):
                Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
                Start-Service sshd
    Linux   : sudo apt install openssh-server  (or dnf);  enable+start ssh.
    The panel detects the service and shows the exact commands. (Uses TCP 22.)

  LOCAL AI (optional, private, free) — Ollama
    Ollama runs local models on Windows, macOS, AND Linux (ollama.com). You pull
    the model yourself; SubnetSlinger just talks to Ollama. Setup:
      1. Install Ollama and start it (it serves on http://localhost:11434).
      2. Pull a TOOL-CAPABLE model — the Deputy drives tools, so the model MUST
         support function calling; not every local model does. Good picks:
             ollama pull llama3.1        (also: qwen2.5, mistral)
      3. In the Deputy: set AI = Ollama, confirm the host, and pick the model
         (the refresh button lists what's installed).
    Each model is a 4-40 GB download and needs the RAM/GPU in section 2. To share
    ONE model server across the team instead, point the Ollama Host at it (sec. 3).

  AI COST, CONTROL & MODEL UPDATES
    - You always see the cost: a live line under the Deputy (and by the Posse)
      shows tokens in/out, the model, and the running $ this chat. Ollama shows
      'local (free)'. Each Deputy turn and Posse run also writes its token/cost
      to the Activity log, so it's in your exportable audit record.
    - You cap it: set a per-chat cap AND a global per-day cap — new turns/runs
      are blocked once hit. The STOP button cancels a run in flight.
    - Known secret shapes are masked in the copy sent to any model (cloud or
      local) — a strong safety net, not an absolute guarantee (see above).
    - New models & current pricing arrive automatically: the model list and rate
      table refresh from a hosted manifest (subnetslinger.com/models.json), so
      new provider models and price changes appear WITHOUT an app update.

  DEPUTY MCP HOSTS (optional — connect the AI to external MCP servers)
    The Deputy can launch MCP servers you configure. Their toolchain is your
    responsibility to install:
      - Node.js  for `npx`-based servers
      - Python + `uv`/`uvx` for `uvx`-based servers
    MCP servers run as local child processes over stdio (no inbound ports).

  LAB TESTING (optional)
    iperf3 is needed on BOTH ends for the Lab Testing throughput test. Easiest: "winget install iperf3".
    If you unzip the iperf.fr build by hand it is Cygwin-based, so keep iperf3.exe AND cygwin1.dll (plus any
    other DLLs) together in one folder that's on PATH — copying iperf3.exe alone fails with
    "cygwin1.dll was not found."


------------------------------------------------------------------------
 5. NETWORK PORTS — the built-in test servers (Local servers tool)
------------------------------------------------------------------------
  Run these only when you use the Local servers tool. They listen on the
  standard service ports below so real gear can point at your workstation.
  Inbound rules are scoped to the app and (on Windows) the Private profile.

    Service          Proto  Port(s)     Notes
    ---------------  -----  ----------  ----------------------------------
    Syslog           UDP    514         collect device logs
    SNMP trap        UDP    162         receive traps
    TFTP             UDP    69          config/image transfer
    DNS              UDP    53          test resolver
    DHCP             UDP    67          test lease server
    RADIUS           UDP    1812-1813   auth + accounting
    TACACS+          TCP    49          auth
    FTP              TCP    21          file transfer
    HTTP             TCP    80          file server
    SFTP/SCP recv    TCP    22          via the OS OpenSSH server (section 4)

  Per-OS notes:
    Windows : the above are opened at install (Private profile, app-scoped).
              Custom/fallback ports → in-app "Add firewall rules" button.
    Linux   : low-port binds are best-effort; when a <1024 bind is refused the
              panel offers a high-port fallback (>1024) automatically — no grant
              needed. (Only live packet Capture needs a grant; see section 3.)
  Outbound: the app makes NO unsolicited outbound connections beyond the
  features you invoke (cloud AI with your key, speed test, WHOIS, public IP,
  and the offline OUI DB's online fallback for unknown vendors).


------------------------------------------------------------------------
 6. WHERE YOUR DATA LIVES
------------------------------------------------------------------------
  Documents/SubnetSlinger      server folders (tftp/http/ftp/dns/radius/
                               tacacs/scp), exports, captures, logs
  Windows  %APPDATA%\SubnetSlinger      settings & state
  Linux    ~/.config/SubnetSlinger      settings & state
  (Dev builds use the "-Dev" suffixed folders.)  Removal: see INSTALL-UNINSTALL.txt.


------------------------------------------------------------------------
 SubnetSlinger — Oregon, USA.  One-time license, every desktop OS, free
 companion apps on phones. Questions: sheriff@subnetslinger.com
========================================================================
