{"all_yanked":false,"avatar_url":"https://avatars.githubusercontent.com/u/37297218","created_at":"2026-04-25T17:26:35.419303Z","description":"Darwin Management NIC Configurator - USB NIC setup with WiFi preservation","download_url":"https://api.flakehub.com/f/Jesssullivan/DarwinNicUtil/2.1.2.tar.gz","labels":["enterprise-bastion","compliance","tui","developer-experience","nat-punchthrough","airgapped-security","nat-traversal"],"mirrored":false,"org":"Jesssullivan","outputs":{"checks":{"doc":"The `checks` flake output contains derivations that will be built by `nix flake check`.\n","name":"checks","outputs":[{"outputs":[{"doc":null,"for_systems":["aarch64-darwin"],"path":["checks","aarch64-darwin","darwin-nic"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"CI test"}],"platform":"aarch64-darwin"},{"outputs":[{"doc":null,"for_systems":["aarch64-linux"],"path":["checks","aarch64-linux","darwin-nic"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"CI test"}],"platform":"aarch64-linux"},{"outputs":[{"doc":null,"for_systems":["x86_64-darwin"],"path":["checks","x86_64-darwin","darwin-nic"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"CI test"}],"platform":"x86_64-darwin"},{"outputs":[{"doc":null,"for_systems":["x86_64-linux"],"path":["checks","x86_64-linux","darwin-nic"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"CI test"}],"platform":"x86_64-linux"}]},"devShells":{"doc":"The `devShells` flake output contains derivations that provide a development environment for `nix develop`.\n","name":"devShells","outputs":[{"outputs":[{"doc":null,"for_systems":["aarch64-darwin"],"path":["devShells","aarch64-darwin","default"],"short_description":"","store_paths":{},"what":"development environment"}],"platform":"aarch64-darwin"},{"outputs":[{"doc":null,"for_systems":["aarch64-linux"],"path":["devShells","aarch64-linux","default"],"short_description":"","store_paths":{},"what":"development environment"}],"platform":"aarch64-linux"},{"outputs":[{"doc":null,"for_systems":["x86_64-darwin"],"path":["devShells","x86_64-darwin","default"],"short_description":"","store_paths":{},"what":"development environment"}],"platform":"x86_64-darwin"},{"outputs":[{"doc":null,"for_systems":["x86_64-linux"],"path":["devShells","x86_64-linux","default"],"short_description":"","store_paths":{},"what":"development environment"}],"platform":"x86_64-linux"}]},"homeModules":{"doc":"The `homeModules` flake output defines importable [Home Manager](https://github.com/nix-community/home-manager) modules.\n","name":"homeModules","outputs":[{"outputs":[{"doc":null,"for_systems":[null],"path":["homeModules","default"],"short_description":null,"store_paths":{},"what":"Home Manager module"},{"doc":null,"for_systems":[null],"path":["homeModules","darwin-nic"],"short_description":null,"store_paths":{},"what":"Home Manager module"},{"doc":null,"for_systems":[null],"path":["homeModules","network-tools"],"short_description":null,"store_paths":{},"what":"Home Manager module"}],"platform":null}]},"overlays":{"doc":"The `overlays` flake output defines [\"overlays\"](https://nixos.org/manual/nixpkgs/stable/#chap-overlays) that can be plugged into Nixpkgs.\nOverlays add additional packages or modify or replace existing packages.\n","name":"overlays","outputs":[{"outputs":[{"doc":null,"for_systems":[null],"path":["overlays","default"],"short_description":null,"store_paths":{},"what":"Nixpkgs overlay"}],"platform":null}]},"packages":{"doc":"The `packages` flake output contains packages that can be added to a shell using `nix shell`.\n","name":"packages","outputs":[{"outputs":[{"doc":null,"for_systems":["aarch64-darwin"],"path":["packages","aarch64-darwin","default"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"package"},{"doc":null,"for_systems":["aarch64-darwin"],"path":["packages","aarch64-darwin","darwin-nic"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"package"},{"doc":null,"for_systems":["aarch64-darwin"],"path":["packages","aarch64-darwin","net-utils"],"short_description":"Network utilities bundle for darwin-nic management workflows","store_paths":{},"what":"package"},{"doc":null,"for_systems":["aarch64-darwin"],"path":["packages","aarch64-darwin","net-utils-extended"],"short_description":"Network utilities bundle for darwin-nic management workflows","store_paths":{},"what":"package"}],"platform":"aarch64-darwin"},{"outputs":[{"doc":null,"for_systems":["aarch64-linux"],"path":["packages","aarch64-linux","default"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"package"},{"doc":null,"for_systems":["aarch64-linux"],"path":["packages","aarch64-linux","darwin-nic"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"package"},{"doc":null,"for_systems":["aarch64-linux"],"path":["packages","aarch64-linux","net-utils"],"short_description":"Network utilities bundle for darwin-nic management workflows","store_paths":{},"what":"package"},{"doc":null,"for_systems":["aarch64-linux"],"path":["packages","aarch64-linux","net-utils-extended"],"short_description":"Network utilities bundle for darwin-nic management workflows","store_paths":{},"what":"package"}],"platform":"aarch64-linux"},{"outputs":[{"doc":null,"for_systems":["x86_64-darwin"],"path":["packages","x86_64-darwin","default"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"package"},{"doc":null,"for_systems":["x86_64-darwin"],"path":["packages","x86_64-darwin","darwin-nic"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"package"},{"doc":null,"for_systems":["x86_64-darwin"],"path":["packages","x86_64-darwin","net-utils"],"short_description":"Network utilities bundle for darwin-nic management workflows","store_paths":{},"what":"package"},{"doc":null,"for_systems":["x86_64-darwin"],"path":["packages","x86_64-darwin","net-utils-extended"],"short_description":"Network utilities bundle for darwin-nic management workflows","store_paths":{},"what":"package"}],"platform":"x86_64-darwin"},{"outputs":[{"doc":null,"for_systems":["x86_64-linux"],"path":["packages","x86_64-linux","default"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"package"},{"doc":null,"for_systems":["x86_64-linux"],"path":["packages","x86_64-linux","darwin-nic"],"short_description":"USB network interface configurator for management access to network devices","store_paths":{},"what":"package"},{"doc":null,"for_systems":["x86_64-linux"],"path":["packages","x86_64-linux","net-utils"],"short_description":"Network utilities bundle for darwin-nic management workflows","store_paths":{},"what":"package"},{"doc":null,"for_systems":["x86_64-linux"],"path":["packages","x86_64-linux","net-utils-extended"],"short_description":"Network utilities bundle for darwin-nic management workflows","store_paths":{},"what":"package"}],"platform":"x86_64-linux"}]}},"pretty_download_url":"https://flakehub.com/f/Jesssullivan/DarwinNicUtil/2.1.2.tar.gz","project":"DarwinNicUtil","readme":"<h1 id=\"readme-darwin-management-nic-configurator\"><a href=\"#readme-darwin-management-nic-configurator\" rel=\"nofollow noopener noreferrer\">Darwin Management NIC Configurator</a></h1>\n<p>Configure a USB Ethernet adapter for out-of-band management without letting it\ntake over normal Wi-Fi or tailnet connectivity.</p>\n<p><code>darwin-nic</code> is aimed at bastion and bench workflows where a Mac needs a\ntemporary management link to network gear while keeping its primary network\npath intact.</p>\n<h2 id=\"readme-status\"><a href=\"#readme-status\" rel=\"nofollow noopener noreferrer\">Status</a></h2>\n<ul>\n<li>macOS is the primary supported platform.</li>\n<li>Linux support is experimental and currently limited.</li>\n<li>Release artifacts are PyPI distributions, GitHub Release wheel/source\nfiles, Nix packages, and FlakeHub releases.</li>\n<li>The PyInstaller spec is retained for manual builds, but standalone binaries\nare not the primary release artifact yet.</li>\n<li>Public docs are built with MkDocs and published at\n<a href=\"https://transscendsurvival.org/DarwinNicUtil/\" rel=\"nofollow noopener noreferrer\">https://transscendsurvival.org/DarwinNicUtil/</a>.</li>\n</ul>\n<h2 id=\"readme-quick-start\"><a href=\"#readme-quick-start\" rel=\"nofollow noopener noreferrer\">Quick Start</a></h2>\n<pre><code><span class=\"source\"><span class=\"comment\"><span class=\"punctuation definition comment\">#</span> Recommended CLI install</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">uv</span></span><span class=\"source\"> tool install darwin-mgmt-nic-configurator</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">darwin-nic</span></span><span class=\"meta\"> status</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">darwin-nic</span></span><span class=\"meta\"> init-config</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">darwin-nic</span></span><span class=\"meta\"> configure <span class=\"meta parameter\"><span class=\"variable parameter\"><span class=\"punctuation definition parameter\">--</span></span></span><span class=\"meta parameter\"><span class=\"variable parameter\">profile</span></span> homelab <span class=\"meta parameter\"><span class=\"variable parameter\"><span class=\"punctuation definition parameter\">--</span></span></span><span class=\"meta parameter\"><span class=\"variable parameter\">preserve-wifi</span></span></span>\n\n<span class=\"comment\"><span class=\"punctuation definition comment\">#</span> Run without installing, using the stable FlakeHub release</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">nix</span></span><span class=\"meta\"> run <span class=\"meta string\"><span class=\"string\"><span class=\"punctuation definition string\">\"</span>https://flakehub.com/f/Jesssullivan/DarwinNicUtil/v2.1.2<span class=\"punctuation definition string\">\"</span></span></span> <span class=\"keyword operator\">--</span> status</span>\n</span></code></pre>\n<p>For a one-off setup without a saved profile:</p>\n<pre><code><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">darwin-nic</span></span><span class=\"source\"> configure <span class=\"punctuation separator\">\\</span>\n  <span class=\"meta parameter\"><span class=\"variable parameter\"><span class=\"punctuation definition parameter\">--</span></span></span><span class=\"meta parameter\"><span class=\"variable parameter\">device-ip</span></span> <span class=\"keyword operator\">&lt;</span>device-ipv4<span class=\"keyword operator\">&gt;</span> \\</span>\n  </span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">--laptop-ip</span></span><span class=\"meta\"> <span class=\"keyword operator\">&lt;</span>usb-nic-ipv4<span class=\"keyword operator\">&gt;</span> \\</span>\n  </span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">--mgmt-network</span></span><span class=\"meta\"> <span class=\"keyword operator\">&lt;</span>cidr<span class=\"keyword operator\">&gt;</span> \\</span>\n  </span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">--preserve-wifi</span></span>\n</span></code></pre>\n<h2 id=\"readme-install\"><a href=\"#readme-install\" rel=\"nofollow noopener noreferrer\">Install</a></h2>\n<table>\n<thead>\n<tr>\n<th>Path</th>\n<th>Use When</th>\n<th>Command</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>PyPI</td>\n<td>You want the normal CLI on your PATH</td>\n<td><code>uv tool install darwin-mgmt-nic-configurator</code></td>\n</tr>\n<tr>\n<td>FlakeHub</td>\n<td>You want a stable Nix release</td>\n<td><code>nix profile install \"https://flakehub.com/f/Jesssullivan/DarwinNicUtil/v2.1.2\"</code></td>\n</tr>\n<tr>\n<td>GitHub flake</td>\n<td>You want the current repository flake</td>\n<td><code>nix profile install github:Jesssullivan/DarwinNicUtil</code></td>\n</tr>\n<tr>\n<td>Source checkout</td>\n<td>You are developing or testing local changes</td>\n<td><code>uv sync --extra dev &amp;&amp; uv run darwin-nic status</code></td>\n</tr>\n</tbody>\n</table>\n<p>Wheel and source distribution files are attached to GitHub Releases and\npublished to PyPI. Standalone binary downloads are not supported yet.</p>\n<p>Home Manager and System Manager modules are available under <code>nix/modules/</code>.\nFor the release shape and productionization summary, see\n<a href=\"https://github.com/Jesssullivan/DarwinNicUtil/blob/HEAD/docs/project-spec.md\" rel=\"nofollow noopener noreferrer\"><code>docs/project-spec.md</code></a>.</p>\n<h2 id=\"readme-commands\"><a href=\"#readme-commands\" rel=\"nofollow noopener noreferrer\">Commands</a></h2>\n<table>\n<thead>\n<tr>\n<th>Command</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>darwin-nic setup</code></td>\n<td>Interactive guided setup wizard</td>\n</tr>\n<tr>\n<td><code>darwin-nic configure</code></td>\n<td>Configure a USB NIC</td>\n</tr>\n<tr>\n<td><code>darwin-nic status</code></td>\n<td>Show interfaces, routes, and bastion diagnostics</td>\n</tr>\n<tr>\n<td><code>darwin-nic dashboard</code></td>\n<td>Show network monitoring status</td>\n</tr>\n<tr>\n<td><code>darwin-nic test</code></td>\n<td>Run basic connectivity checks</td>\n</tr>\n<tr>\n<td><code>darwin-nic restore</code></td>\n<td>Restore saved network service order</td>\n</tr>\n<tr>\n<td><code>darwin-nic config</code></td>\n<td>Show resolved settings and profiles</td>\n</tr>\n<tr>\n<td><code>darwin-nic profiles</code></td>\n<td>List available profiles</td>\n</tr>\n<tr>\n<td><code>darwin-nic init-config</code></td>\n<td>Create a starter config file</td>\n</tr>\n</tbody>\n</table>\n<h2 id=\"readme-configuration\"><a href=\"#readme-configuration\" rel=\"nofollow noopener noreferrer\">Configuration</a></h2>\n<p>Settings are loaded in this order, with later sources overriding earlier ones:</p>\n<table>\n<thead>\n<tr>\n<th>Location</th>\n<th>Purpose</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>/etc/darwin-nic/config.toml</code></td>\n<td>System-wide defaults</td>\n</tr>\n<tr>\n<td><code>~/.config/darwin-nic/config.toml</code></td>\n<td>User defaults</td>\n</tr>\n<tr>\n<td><code>~/.darwin-nic.toml</code></td>\n<td>Legacy user config</td>\n</tr>\n<tr>\n<td><code>./.darwin-nic.toml</code></td>\n<td>Directory-local override</td>\n</tr>\n<tr>\n<td><code>./darwin-nic.toml</code></td>\n<td>Alternate directory-local override</td>\n</tr>\n<tr>\n<td><code>DARWIN_NIC_*</code></td>\n<td>Environment overrides</td>\n</tr>\n</tbody>\n</table>\n<p>Example:</p>\n<pre><code>default_profile = \"homelab\"\n\n[defaults]\npreserve_wifi = true\n\n[profiles.homelab]\ndevice_ip = \"192.168.88.1\"\nlaptop_ip = \"192.168.88.100\"\nmgmt_network = \"192.168.88.0/24\"\ndevice_name = \"Lab Management Device\"\ndevice_type = \"network\"\n</code></pre>\n<p>See <code>examples/config.toml</code> for a fuller profile example.</p>\n<h2 id=\"readme-bastion-notes\"><a href=\"#readme-bastion-notes\" rel=\"nofollow noopener noreferrer\">Bastion Notes</a></h2>\n<p>For a generic <code>tailnet -&gt; bastion host -&gt; USB OOB NIC -&gt; managed network device</code> flow:</p>\n<ul>\n<li>keep <code>mgmt_network</code> aligned with the real management subnet;</li>\n<li>use <code>darwin-nic status</code> before making privileged changes;</li>\n<li>use <code>--dry-run</code> to preview interface and route changes;</li>\n<li>pre-authenticate with <code>sudo -v</code> for non-interactive wrappers;</li>\n<li>check <code>status</code> when raw or link-layer tools work but ordinary sockets fail.</li>\n</ul>\n<p>On macOS, <code>status</code> includes <code>scutil --nwi</code>, Tailscale system-extension state,\nand recent NECP socket-drop hints when available.</p>\n<p>Device-specific hostnames, credentials, OOB MAC addresses, and switch policy\nbelong in downstream operator repositories, not in this generic tool.</p>\n<h2 id=\"readme-safety\"><a href=\"#readme-safety\" rel=\"nofollow noopener noreferrer\">Safety</a></h2>\n<ul>\n<li>Protected interfaces such as Wi-Fi, loopback, and system virtual links are\nnot modified.</li>\n<li><code>--preserve-wifi</code> keeps the primary network path ahead of the USB NIC.</li>\n<li>Dry-run mode previews intended changes without applying them.</li>\n<li>The emergency restore helper is available at <code>scripts/emergency-restore.sh</code>.</li>\n</ul>\n<h2 id=\"readme-requirements\"><a href=\"#readme-requirements\" rel=\"nofollow noopener noreferrer\">Requirements</a></h2>\n<ul>\n<li>Python 3.14+ for source and uv installs.</li>\n<li>Nix for flake-based package usage.</li>\n<li>A USB-to-Ethernet adapter.</li>\n<li>macOS for the full current feature set.</li>\n</ul>\n<h2 id=\"readme-development\"><a href=\"#readme-development\" rel=\"nofollow noopener noreferrer\">Development</a></h2>\n<pre><code><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">just</span></span><span class=\"source\"> dev</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">just</span></span><span class=\"meta\"> check</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">just</span></span><span class=\"meta\"> test</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">just</span></span><span class=\"meta\"> docs-build</span>\n</span><span class=\"meta\"><span class=\"meta\"><span class=\"variable function\">uv</span></span><span class=\"meta\"> build</span>\n</span></code></pre>\n<p>Run <code>just</code> with no arguments to see all recipes.</p>\n<h2 id=\"readme-artifacts\"><a href=\"#readme-artifacts\" rel=\"nofollow noopener noreferrer\">Artifacts</a></h2>\n<p>Current release artifacts are:</p>\n<ul>\n<li>PyPI distribution for <code>darwin-mgmt-nic-configurator</code>;</li>\n<li>GitHub Release wheel and source distribution files;</li>\n<li>Nix flake package outputs, including FlakeHub <code>v2.1.2</code>;</li>\n<li>MkDocs site artifacts from the docs workflow.</li>\n</ul>\n<p>GitHub Release, PyPI, FlakeHub, and docs workflows are present for tag-based\npublication. Standalone binary distribution remains a tracked release follow-up.</p>\n<p>Public artifact URLs:</p>\n<ul>\n<li>Docs: <a href=\"https://transscendsurvival.org/DarwinNicUtil/\" rel=\"nofollow noopener noreferrer\">https://transscendsurvival.org/DarwinNicUtil/</a></li>\n<li>PyPI: <a href=\"https://pypi.org/project/darwin-mgmt-nic-configurator/\" rel=\"nofollow noopener noreferrer\">https://pypi.org/project/darwin-mgmt-nic-configurator/</a></li>\n<li>Releases: <a href=\"https://github.com/Jesssullivan/DarwinNicUtil/releases\" rel=\"nofollow noopener noreferrer\">https://github.com/Jesssullivan/DarwinNicUtil/releases</a></li>\n<li>FlakeHub: <a href=\"https://flakehub.com/f/Jesssullivan/DarwinNicUtil\" rel=\"nofollow noopener noreferrer\">https://flakehub.com/f/Jesssullivan/DarwinNicUtil</a></li>\n</ul>\n","repo_url":"https://github.com/Jesssullivan/DarwinNicUtil","revision":"1c9f85237961df4682c02c656590cd330961634b","simplified_version":"2.1.2","source_github_owner_repo_pair":"Jesssullivan/DarwinNicUtil","source_subdirectory":null,"spdx_identifier":"Zlib","version":"2.1.2","visibility":"public"}