run: quiet relay diagnostics, fix log prefix, document no-root (#659)

Author: piscisaureus

cmd/clawpatrol/integrations.go

@@ -400,7 +400,7 @@ func installClaudeCodeOAuthShim(cmd []string) {
 		dir = filepath.Join(defaultClawpatrolDir(), "claude-config")
 	}
 	if err := os.MkdirAll(dir, 0o700); err != nil {
-		log.Printf("clawpatrol: claude oauth shim: mkdir %s: %v", dir, err)
+		fmt.Fprintf(os.Stderr, "[clawpatrol] claude oauth shim: mkdir %s: %v\n", dir, err)
 		return
 	}
 	credPath := filepath.Join(dir, ".credentials.json")
@@ -414,7 +414,7 @@ func installClaudeCodeOAuthShim(cmd []string) {
 		}
 	}
 	if err := writeClaudeCodeCredentials(credPath, bearer); err != nil {
-		log.Printf("clawpatrol: claude oauth shim: write credentials: %v", err)
+		fmt.Fprintf(os.Stderr, "[clawpatrol] claude oauth shim: write credentials: %v\n", err)
 		return
 	}
 	// Redirect Claude Code's credential read onto our synthesized file
@@ -433,7 +433,7 @@ func installClaudeCodeOAuthShim(cmd []string) {
 // makes them work. Printed instead of silently rewriting the worker's
 // environment and config dir (R&D decision, 2026-06-03).
 func warnClaudeCodeRemoteControlDisabled() {
-	log.Printf(`clawpatrol: Claude Code /remote-control and other claude.ai
+	fmt.Fprintf(os.Stderr, `[clawpatrol] Claude Code /remote-control and other claude.ai
 subscription-only features are disabled in this session: ANTHROPIC_AUTH_TOKEN
 is set, so Claude Code treats this as API-key auth and gates them off locally.
 
@@ -444,7 +444,8 @@ To enable them, opt into the OAuth shim:
 The shim writes a synthesized .credentials.json and points CLAUDE_CONFIG_DIR at
 it for the child. Because that shadows your existing ~/.claude (skills, memory,
 MCP servers, project state), it is off by default — set CLAUDE_CONFIG_DIR to
-your own dir first if you want both. See doc/claude-code-oauth.md.`)
+your own dir first if you want both. See doc/claude-code-oauth.md.
+`)
 }
 
 // writeClaudeCodeCredentials emits the JSON shape Claude Code's

cmd/clawpatrol/relay_linux.go

@@ -46,6 +46,25 @@ import (
 	"golang.org/x/sys/unix"
 )
 
+// relayDebug gates the relay / relay-worker diagnostic chatter (port
+// auto-expose, the host-loopback forwarder line, per-connection
+// errors). It's noise during a normal `clawpatrol run`, so it's off
+// unless CLAWPATROL_DEBUG is set. Genuine functional warnings (the ⚠
+// lines) print regardless. Evaluated once — the env is inherited
+// across the relay-worker re-exec.
+var relayDebug = func() bool {
+	v := os.Getenv("CLAWPATROL_DEBUG")
+	return v != "" && v != "0"
+}()
+
+// relayDebugf writes a relay diagnostic line to stderr only when
+// CLAWPATROL_DEBUG is set.
+func relayDebugf(format string, a ...any) {
+	if relayDebug {
+		fmt.Fprintf(os.Stderr, format, a...)
+	}
+}
+
 // --- BPF + seccomp ABI (re-declared because x/sys/unix has no SockFprog
 // helper for the SECCOMP_SET_MODE_FILTER syscall) ---------------------
 
@@ -234,7 +253,7 @@ func runRelaySupervisor(_ []string) {
 	// and we don't want it auto-exposed back to the host.
 	workerPID, err := recvWorkerPID(lbRC)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "[clawpatrol relay] read worker pid: %v\n", err)
+		relayDebugf("[clawpatrol relay] read worker pid: %v\n", err)
 		return
 	}
 
@@ -257,7 +276,7 @@ func runRelaySupervisor(_ []string) {
 			if errors.Is(err, unix.ENOENT) {
 				return
 			}
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay] notif_recv: %v\n", err)
+			relayDebugf("[clawpatrol relay] notif_recv: %v\n", err)
 			return
 		}
 
@@ -275,7 +294,7 @@ func runRelaySupervisor(_ []string) {
 			_ = notifSendContinue(notifyFD, n.ID)
 
 			if perr != nil {
-				fmt.Fprintf(os.Stderr, "[clawpatrol relay] inspect listen sockfd: %v\n", perr)
+				relayDebugf("[clawpatrol relay] inspect listen sockfd: %v\n", perr)
 				continue
 			}
 			seenMu.Lock()
@@ -290,13 +309,13 @@ func runRelaySupervisor(_ []string) {
 			host := mirrorBindScope(family, ip)
 			ln, lerr := net.Listen("tcp", net.JoinHostPort(host, fmt.Sprintf("%d", port)))
 			if lerr != nil {
-				fmt.Fprintf(os.Stderr, "[clawpatrol relay] could not tunnel %s:%d: %v\n", host, port, lerr)
+				relayDebugf("[clawpatrol relay] could not tunnel %s:%d: %v\n", host, port, lerr)
 				seenMu.Lock()
 				delete(seen, port)
 				seenMu.Unlock()
 				continue
 			}
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay] auto-expose %s:%d → agent netns\n", host, port)
+			relayDebugf("[clawpatrol relay] auto-expose %s:%d → agent netns\n", host, port)
 			go acceptLoop(ln, port, workerRC)
 		} else {
 			_ = notifSendContinue(notifyFD, n.ID)
@@ -349,7 +368,7 @@ func runLoopbackSupervisorLoop(lbRC syscall.RawConn) {
 			if errors.Is(err, io.EOF) {
 				return
 			}
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay] loopback recv: %v\n", err)
+			relayDebugf("[clawpatrol relay] loopback recv: %v\n", err)
 			return
 		}
 		go handleLoopbackJob(ip, port, fd)
@@ -369,12 +388,12 @@ func handleLoopbackJob(ip [4]byte, port uint16, fd int) {
 
 	dst := net.IPv4(ip[0], ip[1], ip[2], ip[3])
 	if !dst.IsLoopback() {
-		fmt.Fprintf(os.Stderr, "[clawpatrol relay] refusing non-loopback dst %s\n", dst)
+		relayDebugf("[clawpatrol relay] refusing non-loopback dst %s\n", dst)
 		return
 	}
 	host, err := net.Dial("tcp", net.JoinHostPort(dst.String(), fmt.Sprintf("%d", port)))
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "[clawpatrol relay] dial host %s:%d: %v\n", dst, port, err)
+		relayDebugf("[clawpatrol relay] dial host %s:%d: %v\n", dst, port, err)
 		return
 	}
 	defer func() { _ = host.Close() }()
@@ -501,7 +520,7 @@ func procPeekListener(pid, sockfd int) (uint16, net.IP, int, error) {
 		port, ip, ok, err := scanProcNetTCP(t.path, inode, t.ipHex)
 		if err != nil && !errors.Is(err, os.ErrNotExist) {
 			// Surface IO errors but keep trying the other family.
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay] read %s: %v\n", t.path, err)
+			relayDebugf("[clawpatrol relay] read %s: %v\n", t.path, err)
 			continue
 		}
 		if ok {
@@ -623,12 +642,12 @@ func acceptLoop(ln net.Listener, port uint16, workerRC syscall.RawConn) {
 	for {
 		c, err := ln.Accept()
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay] accept on :%d ended: %v\n", port, err)
+			relayDebugf("[clawpatrol relay] accept on :%d ended: %v\n", port, err)
 			return
 		}
 		fd, perr := tcpRawFD(c)
 		if perr != nil {
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay] raw fd on :%d: %v\n", port, perr)
+			relayDebugf("[clawpatrol relay] raw fd on :%d: %v\n", port, perr)
 			_ = c.Close()
 			continue
 		}
@@ -638,7 +657,7 @@ func acceptLoop(ln net.Listener, port uint16, workerRC syscall.RawConn) {
 		err = sendJob(workerRC, portBuf[:], rights)
 		_ = c.Close()
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay] sendmsg to worker on :%d: %v\n", port, err)
+			relayDebugf("[clawpatrol relay] sendmsg to worker on :%d: %v\n", port, err)
 			return
 		}
 	}
@@ -723,7 +742,7 @@ func runRelayWorker(_ []string) {
 	// Tell the supervisor our PID so it can ignore the listen() trap
 	// triggered by our own host-loopback forwarder below.
 	if err := sendWorkerPID(lbRC); err != nil {
-		fmt.Fprintf(os.Stderr, "[clawpatrol relay-worker] send pid: %v\n", err)
+		relayDebugf("[clawpatrol relay-worker] send pid: %v\n", err)
 		// Continue — supervisor's loopback loop will block on recv
 		// and the auto-expose direction will still work.
 	}
@@ -769,7 +788,7 @@ func relayWorkerLoop(rc syscall.RawConn, handle func(uint16, int)) {
 			if errors.Is(err, io.EOF) {
 				return
 			}
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay-worker] recv: %v\n", err)
+			relayDebugf("[clawpatrol relay-worker] recv: %v\n", err)
 			return
 		}
 		go handle(port, fd)
@@ -901,7 +920,7 @@ func handleJob(port uint16, fd int) {
 
 	inner, err := dialAgentLoopback(port)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "[clawpatrol relay-worker] dial 127.0.0.1:%d: %v\n", port, err)
+		relayDebugf("[clawpatrol relay-worker] dial 127.0.0.1:%d: %v\n", port, err)
 		return
 	}
 	defer func() { _ = inner.Close() }()
@@ -981,7 +1000,7 @@ func setupHostLoopbackForwarder(lbRC syscall.RawConn) error {
 		_ = ln.Close()
 		return fmt.Errorf("install REDIRECT rules: %w", err)
 	}
-	fmt.Fprintf(os.Stderr, "[clawpatrol relay-worker] host-loopback forwarder on 127.0.0.1:%d (REDIRECT installed)\n", fwdPort)
+	relayDebugf("[clawpatrol relay-worker] host-loopback forwarder on 127.0.0.1:%d (REDIRECT installed)\n", fwdPort)
 	go loopbackAcceptLoop(ln, lbRC)
 	return nil
 }
@@ -1065,18 +1084,18 @@ func loopbackAcceptLoop(ln net.Listener, lbRC syscall.RawConn) {
 	for {
 		c, err := ln.Accept()
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay-worker] loopback accept ended: %v\n", err)
+			relayDebugf("[clawpatrol relay-worker] loopback accept ended: %v\n", err)
 			return
 		}
 		fd, perr := tcpRawFD(c)
 		if perr != nil {
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay-worker] loopback raw fd: %v\n", perr)
+			relayDebugf("[clawpatrol relay-worker] loopback raw fd: %v\n", perr)
 			_ = c.Close()
 			continue
 		}
 		origIP, origPort, perr := getOriginalDst(fd)
 		if perr != nil {
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay-worker] SO_ORIGINAL_DST: %v\n", perr)
+			relayDebugf("[clawpatrol relay-worker] SO_ORIGINAL_DST: %v\n", perr)
 			_ = c.Close()
 			continue
 		}
@@ -1085,7 +1104,7 @@ func loopbackAcceptLoop(ln net.Listener, lbRC syscall.RawConn) {
 		err = sendJob(lbRC, frame[:], rights)
 		_ = c.Close()
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "[clawpatrol relay-worker] loopback sendmsg: %v\n", err)
+			relayDebugf("[clawpatrol relay-worker] loopback sendmsg: %v\n", err)
 			return
 		}
 	}

site/doc/cli.md

@@ -95,6 +95,36 @@ The agent sees a normal network — outbound flows just route through
 the gateway, which matches each request against the rules, injects
 the configured credential, and forwards.
 
+#### No root inside `clawpatrol run` (Linux)
+
+The wrapped command runs in an unprivileged user namespace. As a
+consequence of how Linux user namespaces work, that namespace has no
+mapped root: your own uid is the only one mapped in, host root (uid 0)
+is not. So commands that need real root won't work — `sudo` fails
+with messages like:
+
+```
+sudo: /etc/sudo.conf is owned by uid 65534, should be 0
+sudo: The "no new privileges" flag is set, which prevents sudo from running as root.
+```
+
+The first is the namespace mapping root-owned files to "nobody"
+(65534); the second is the `no_new_privileges` flag clawpatrol sets to
+install its unprivileged seccomp filter. This isn't a deliberate
+restriction — it falls out of running unprivileged, and the host's own
+`sudo` is unaffected outside the wrapper.
+
+If a command needs to act as root:
+
+- **Install the tooling on the host first**, then launch — e.g.
+  `sudo apt-get install -y postgresql-client && clawpatrol run -- psql …`.
+  Many tools can also be unpacked into a local prefix (e.g.
+  `dpkg-deb -x`) without root at all.
+- **Use `--whole-machine`** (see `clawpatrol join --whole-machine`).
+  It routes traffic at the host level instead of per-process, so the
+  command runs in the normal host environment where `sudo` works —
+  you run it directly, not through `clawpatrol run`.
+
 ### `clawpatrol test`
 
 Replay recorded gateway actions against a candidate HCL policy and
@@ -174,6 +204,7 @@ device-side knobs:
 | Variable | Effect |
 |---|---|
 | `CLAWPATROL_RUN_CONF` | Override the WG conf path `clawpatrol run` reads |
+| `CLAWPATROL_DEBUG` | Print the relay / auto-expose diagnostic lines, which are otherwise silent |
 | `CLAWPATROL_NO_ENV` | Skip the env pushdown (`SSL_CERT_FILE`, placeholders) when wrapping a command |
 | `CLAWPATROL_TELEMETRY` | `0` to disable telemetry (same as `DO_NOT_TRACK=1`) |
 | `DO_NOT_TRACK` | Standard opt-out, honored |