In-VM exec agent for Cocoon-managed VMs. Listens on virtio-vsock and runs commands on behalf of host-side callers (vk-cocoon, the cocoon CLI, anything else with vsock access on the same node), replacing SSH for control-plane operations like kubectl exec. It also handles post-clone reseed — injecting host entropy into the guest CRNG and regenerating /etc/machine-id so cloned VMs don't stay correlated.

Documentation: cocoonstack.github.io/cocoon-agent (source in docs/).

host (cocoon node)                                  guest VM
+------------------+                            +------------------------+
| vk-cocoon        |                            | systemd                |
|                  |                            |   |                    |
| Provider.Run-    |  vsock://<cid>:<port>      |   v                    |
| InContainer ---> |--------------------------->| cocoon-agent serve     |
|                  |       (kubectl exec)       |   |                    |
| (eventually via  |                            |   v                    |
|  cocoon vm exec) |                            | exec.Command(argv)     |
+------------------+                            +------------------------+

v0.1.x — Linux + Windows guests supported. PTY mode planned; see Roadmap.

cocoon-agent client --cid 3 --port 1024 -- echo "hello from guest"

Full steps in Usage.

• Architecture — why cocoon-agent exists, current status, the wire protocol, and the roadmap
• Installation — baking the Linux binary into an image, the Windows service installer, and pipe-mode limitations
• Usage — smoke-testing an agent from the host with the client subcommand
• Configuration — environment variables and CLI flags
• Build — cross-compiling for Linux and Windows guests

make all          # tidy + fmt + lint + test + build
make test         # go test -race -cover
make lint         # golangci-lint on linux + darwin + windows
make fmt-check    # gofumpt + goimports check
make help         # full target list

• cocoon — VM engine
• vk-cocoon — virtual-kubelet provider; the planned primary consumer of cocoon-agent
• cocoon-common — shared metadata / annotation contract

MIT