Quick Start

Get a USB management NIC configured without letting it take over normal Wi-Fi or tailnet connectivity.

Installation

Use PyPI for the normal CLI, FlakeHub for stable Nix use, and source checkout only when developing or validating local changes.

uv tool install darwin-mgmt-nic-configurator
darwin-nic setup

# Stable release
nix run "https://flakehub.com/f/Jesssullivan/DarwinNicUtil/v2.1.2" -- setup

# Direct GitHub flake reference
nix run github:Jesssullivan/DarwinNicUtil -- configure \
  --device-ip 192.168.88.1 \
  --laptop-ip 192.168.88.100 \
  --mgmt-network 192.168.88.0/24 \
  --preserve-wifi

git clone https://github.com/Jesssullivan/DarwinNicUtil.git
cd DarwinNicUtil

uv sync --extra dev
uv run darwin-nic setup

Interactive Setup

The guided setup wizard walks through USB NIC detection, IP configuration, Wi-Fi preservation, and a connectivity check.

darwin-nic setup

sequenceDiagram
    participant U as User
    participant D as darwin-nic
    participant N as Network

    U->>D: darwin-nic setup
    D->>N: Scan for USB NICs
    N-->>D: Found en7 (USB Ethernet)
    D->>U: Confirm interface?
    U->>D: Yes
    D->>N: Configure IP
    D->>N: Preserve Wi-Fi priority
    D->>N: Test target reachability
    D-->>U: Complete

Configuration File

Save network settings to avoid typing IPs every time:

# Initialize config file
darwin-nic init-config

# View current settings
darwin-nic config

# List profiles
darwin-nic profiles

Edit ~/.config/darwin-nic/config.toml:

default_profile = "homelab"

[defaults]
preserve_wifi = true

[profiles.homelab]
device_ip = "192.168.88.1"
laptop_ip = "192.168.88.100"
mgmt_network = "192.168.88.0/24"
device_name = "Lab Management Device"
device_type = "network"

Then run:

darwin-nic configure --profile homelab --preserve-wifi

CLI Configuration

For scripting or one-off setup:

darwin-nic configure \
  --device-ip 192.168.88.1 \
  --laptop-ip 192.168.88.100 \
  --mgmt-network 192.168.88.0/24 \
  --preserve-wifi

Options

Verify Configuration

# Check status, routes, and bastion/OOB diagnostics
darwin-nic status

# Test connectivity
darwin-nic test

# Real-time monitoring
darwin-nic dashboard

If status shows the USB interface missing from scutil --nwi while the Tailscale system extension is active, ordinary sockets may be blocked by macOS NECP even though link-layer tools and ARP still work.

Integration Surfaces

Troubleshooting

USB Interface Not Detected

# Check if adapter is recognized
networksetup -listallhardwareports

Permission Denied

# Pre-authenticate sudo, then rerun configure
sudo -v
darwin-nic configure \
  --device-ip 192.168.88.1 \
  --laptop-ip 192.168.88.100 \
  --mgmt-network 192.168.88.0/24

Emergency Recovery

./scripts/emergency-restore.sh