cocoon-agent

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.

Why

Cocoon's host components (vk-cocoon, cocoon CLI) and the VMs they manage always sit on the same node. SSH inside the guest carries a lot of weight for that scenario:

• requires sshd installed and running
• requires the guest network stack to be up + an IP to be reachable
• requires per-VM credentials to be provisioned and rotated
• comes with the full SSH protocol surface (handshake, key exchange, host key trust)

vsock is host↔guest only, has no IP layer, and the kernel vhost_vsock module is the auth boundary — anything that can connect from the host is already privileged on that host. cocoon-agent leverages this for a small focused daemon that gives kubectl-exec semantics (stdin / stdout / stderr / exit code) with none of those dependencies.

Status

v0.1 — first working version. See Roadmap for what's coming.

Architecture

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)     |
+------------------+                            +------------------------+

The wire protocol is line-delimited JSON, one frame per line, both directions. The first frame is MsgExec carrying argv; subsequent frames are stdin chunks (MsgStdin / MsgStdinClose) from the client and stdout/stderr chunks plus the final exit code (MsgStdout / MsgStderr / MsgExit) from the agent.

See agent/protocol.go for the complete schema.

Build

make build              # local build
GOOS=linux make build   # cross-compile for guest (amd64)
GOOS=linux GOARCH=arm64 make build

Install in a guest

cocoon-agent is intended to be baked into Cocoon-managed images alongside the existing OCI bundles in cocoon/os-image:

COPY cocoon-agent /usr/local/bin/cocoon-agent
COPY cocoon-agent.service /etc/systemd/system/cocoon-agent.service
RUN systemctl enable cocoon-agent.service

The systemd unit is in packaging/cocoon-agent.service.

Smoke test from the host

cocoon-agent ships a client subcommand for vsock smoke tests without needing to plumb through cocoon CLI / vk-cocoon. Get the VM's CID from cocoon vm inspect and run:

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

Exit codes pass through.

Configuration

Env var	Default	Notes
AGENT_LOG_LEVEL	info	debug / info / warn / error (projecteru2/core/log levels)

CLI flags:

Flag	Default	Notes
serve --port	1024	vsock port to bind on
client --cid	required	target VM CID (host-side)
client --port	1024	matches serve --port

Roadmap

Version	Scope
v0.1 (current)	exec, stdin streaming, stdout/stderr, exit code; vsock listener; cobra CLI
v0.2	PTY mode (tty: true), window resize messages, signal forwarding
v0.3	Windows guest support (vsock-windows driver), MSI installer
v0.4	Streaming cocoon vm exec host-side adapter (subprocess-friendly for vk-cocoon RunInContainer)

Related

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

Development

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

License

MIT