feat(vm): --net tap — attach qemu to a pre-created host TAP (bridged/routed)

Spec.Tap + 'vm run --net tap --tap <ifname>' emit '-netdev tap,id=net0,ifname=<tap>,script=no,
downscript=no' instead of user-mode SLIRP; the macOS virtio-net front-end is unchanged (guest just
re-DHCPs off the bridge). This is the by-name attach side of the cocoon networking design — same
forwarding plane as cocoon's CH/FC VMs when the TAP is on the same bridge/CNI. Darwin-safe (pure
qemu args, no netlink). Phase 3a; importing cocoon's network/bridge to AUTO-create the TAP (netlink,
linux-only) is the follow-up wiring.

Author: CMGS

cmd/vm/commands.go

@@ -97,4 +97,6 @@ func addVMFlags(cmd *cobra.Command) {
 	cmd.Flags().String("ovmf-vars", "", "OVMF_VARS template (copied per-VM)")
 	cmd.Flags().Bool("random-smbios", false, "inject a unique Apple SMBIOS identity per VM (serial/MLB/UUID/ROM)")
 	cmd.Flags().String("vnc-password", "", "set a VNC password (≤8 chars) so macOS Screen Sharing can connect (QEMU password auth)")
+	cmd.Flags().String("net", "user", "network mode: user (SLIRP + --ssh-port hostfwd) | tap (bridged/routed via --tap)")
+	cmd.Flags().String("tap", "", "pre-created host TAP ifname for --net tap (e.g. attached to a bridge / cocoon CNI)")
 }

cmd/vm/handler.go

@@ -71,6 +71,8 @@ type record struct {
 	MAC         string       `json:"mac,omitempty"`
 	SMBIOS      *qemu.SMBIOS `json:"smbios,omitempty"`
 	VNCPass     string       `json:"vnc_password,omitempty"`
+	NetMode     string       `json:"net_mode,omitempty"`
+	Tap         string       `json:"tap,omitempty"`
 }
 
 func stateDir(cmd *cobra.Command) string {
@@ -148,9 +150,15 @@ func (h *Handler) create(cmd *cobra.Command, image string) (*record, error) {
 	vnc, _ := cmd.Flags().GetInt("vnc")
 	ssh, _ := cmd.Flags().GetInt("ssh-port")
 	vncPass, _ := cmd.Flags().GetString("vnc-password")
+	netMode, _ := cmd.Flags().GetString("net")
+	tap, _ := cmd.Flags().GetString("tap")
+	if netMode == "tap" && tap == "" {
+		return nil, fmt.Errorf("--net tap requires --tap <ifname>")
+	}
 	r := &record{
 		Name: name, Image: image, ImageDigest: digest, Disk: overlay, OpenCore: oc, OVMFCode: code, OVMFVars: ovmfVars,
-		CPUs: cpus, Memory: mem, VNCDisp: vnc, SSHPort: ssh, VNCPass: vncPass, Created: time.Now().Format(time.RFC3339),
+		CPUs: cpus, Memory: mem, VNCDisp: vnc, SSHPort: ssh, VNCPass: vncPass, NetMode: netMode, Tap: tap,
+		Created: time.Now().Format(time.RFC3339),
 	}
 	if random, _ := cmd.Flags().GetBool("random-smbios"); random {
 		if err := assignSMBIOS(dir, oc, r); err != nil {
@@ -184,6 +192,9 @@ func (h *Handler) launch(dir string, r *record) error {
 		CPUs: r.CPUs, Memory: r.Memory, VNCDisp: r.VNCDisp, SSHPort: r.SSHPort, MAC: r.MAC, VNCPass: r.VNCPass,
 		MonSock: filepath.Join(dir, "monitor.sock"), QMPSock: filepath.Join(dir, "qmp.sock"),
 	}
+	if r.NetMode == "tap" {
+		spec.Tap = r.Tap
+	}
 	pidfile := filepath.Join(dir, "qemu.pid")
 	args := append(spec.Args(), "-daemonize", "-pidfile", pidfile)
 	c := exec.Command("qemu-system-x86_64", args...)

qemu/launch.go

@@ -28,6 +28,7 @@ type Spec struct {
 	QMPSock  string // optional QMP unix socket
 	MAC      string // optional guest NIC MAC (set to the SMBIOS ROM for --random-smbios)
 	VNCPass  string // optional VNC password (enables QEMU password auth; set via monitor after launch)
+	Tap      string // optional pre-created host TAP ifname; set => bridged/routed (-netdev tap) instead of user-mode
 }
 
 // Args returns the qemu-system-x86_64 argument vector for the macOS guest.
@@ -52,9 +53,14 @@ func (s Spec) Args() []string {
 		"-device", "ide-hd,bus=sata.4,drive=MacHDD",
 		"-device", "vmware-svga",
 	}
-	if s.SSHPort > 0 {
+	switch {
+	case s.Tap != "":
+		// attach to a pre-created host TAP (cocoon's network plane / a bridge owns IP+forwarding);
+		// the macOS virtio-net front-end is unchanged, the guest just re-DHCPs off the bridge
+		a = append(a, "-netdev", "tap,id=net0,ifname="+s.Tap+",script=no,downscript=no")
+	case s.SSHPort > 0:
 		a = append(a, "-netdev", fmt.Sprintf("user,id=net0,hostfwd=tcp::%d-:22", s.SSHPort))
-	} else {
+	default:
 		a = append(a, "-netdev", "user,id=net0")
 	}
 	nic := "virtio-net-pci,netdev=net0,id=net0"