clawk Ubuntu Port Analysis

Date: 2026-07-22
Repo: https://github.com/Opfour/clawk (fork of clawkwork/clawk)

Current Linux State

Linux backend exists (Firecracker microVM) but is experimental/pre-1.0.
Code is well-architected with clean abstractions (machine.Backend interface, Provider pattern).

Known Limitations (from source code)

1. NO VIRTIO-FS (live file sharing) -- BIGGEST GAP

• macOS: code is live-mounted into VM via virtio-fs
• Linux: worktree is "baked" (copied) into rootfs at create time
• Host edits don't propagate to VM -- must clawk down && clawk to rebuild
• Firecracker doesn't bundle virtiofsd
• clawk kernel already has CONFIG_NET_9P_FD compiled in
• Could wire 9P-over-vsock for the worktree mount instead of baking
• Files: internal/sandbox/firecracker_linux.go (bakeWorktree func, line ~150)
  machine/firecracker/firecracker_linux.go (checkSpec rejects Shares, line ~91)

2. SINGLE SANDBOX AT A TIME

• One shared bridge (clawkbr0) with one fixed guest IP (192.168.127.x)
• Two firecracker sandboxes running simultaneously = network collision
• Fix: allocate /30 from 192.168.127.0/24 per sandbox
• Files: internal/sandbox/linux_shared.go (linuxBridge const, ensureLinuxBridge, ensureTAP)

3. REQUIRES SUDO FOR NETWORKING

• Every clawk command calls sudo -n for TAP/bridge setup
• No passwordless sudo = fails silently
• Fix: setcap CAP_NET_ADMIN on firecracker binary, or polkit rule
• Files: internal/sandbox/linux_shared.go (runSudo func, line ~112)

4. FIRECRACKER BINARY NOT AUTO-INSTALLED

• Requires firecracker on PATH manually
• Could auto-download (mirror ciEnsureKernel pattern)
• Files: internal/sandbox/firecracker_linux.go (exec.LookPath checks, lines 89, 170)

5. ROOTFS BUILD ASSUMES macOS TOOLCHAIN

• Guest binary build step uses macOS cross-compile path
• Linux runs natively but build scripts may need adjustment
• Files: internal/guestbuild/ (Build func)

Hardware Check (this machine)

• /dev/kvm: present (crw-rw---- root kvm)
• VT-x: enabled (32 cpuinfo entries)
• CPU: x86_64
• OS: Ubuntu 26.04 LTS
• GPU: Quadro RTX 3000 6GB (irrelevant for clawk but noted)
• Go: 1.24.6 installed at ~/go/bin (clawk needs 1.26+)
• Go 1.26.0 downloaded at /tmp/go1.26.tar.gz (not yet extracted)

Effort Estimate

• Named namespace lifecycle resolves VM/state under default #1 (virtiofs/9P): Medium -- wire Shares field, add 9P mount config
• 支持bwrap么 #2 (per-sandbox net): Small -- allocate /30 per sandbox
• Project development #3 (sudo-free): Small -- setcap or polkit
• env ( ) profile.d file written 0600 root:root — forwarded vars never reach the agent user #4 (firecracker bootstrap): Small -- auto-download
• env: aliases, defaults, and literals; fix profile.d perms (#4) #5 (build toolchain): Small-Medium
• Total: 2-3 days focused Go work

Key Files

• internal/sandbox/firecracker_linux.go -- FirecrackerProvider (381 lines)
• internal/sandbox/linux_shared.go -- bridge/TAP/kernel fetch (337 lines)
• machine/firecracker/firecracker_linux.go -- VM lifecycle (871 lines)
• machine/firecracker/firecracker.go -- package doc
• machine/kernel/kernel.go -- kernel config (9P, virtio-fs refs)
• machine/machine.go -- Backend interface

Build Requirements

• Go 1.26+ (go.mod requires go 1.26.0)
• firecracker binary on PATH
• /dev/kvm access (kvm group)
• sudo for TAP/bridge (until fixed)