[Feature]: Add vsock-based control plane for microVMs (job exec + results + streaming)

[aniketmaurya]

Problem statement

We already support SSH access into microVMs for “human debugging / exploration.” SSH is great for interactive usage, but it’s not the right primitive for automated job execution, result collection, and tight security defaults.

We should add a vsock-based control plane to run commands/jobs and return results efficiently without requiring guest IP networking.

Proposed design

In-guest: vsock-agent

A small daemon started at boot (systemd or init), listening on a fixed vsock port, e.g. PORT=5000.

Responsibilities:

• authenticate requests (token or per-VM secret)
• spawn commands with policy controls (timeouts, resource limits)
• stream stdout/stderr
• implement file transfer endpoints (optional)
• maintain job registry (job_id → status)

Security requirements:

• default run as non-root user
• hard caps:
  • max runtime per request
  • max output bytes
  • max file transfer size
• require auth token per request (passed on every call)

Host-side: vsock-client

A library + CLI integration used by our control plane:

• connect to VM CID and port
• request/response protocol
• stream logs
• fetch artifacts

Additional context

Target outcomes

Implement a vsock agent inside the microVM + a host-side client to support:

1. Command/job execution

• Run command in guest
• Return: exit_code, stdout, stderr, duration_ms
• Optional: env, cwd, stdin

2. Streaming logs

• Stream stdout/stderr incrementally for long-running jobs
• Support cancellation

3. File transfer (optional but strongly recommended)

• put_file(local → guest)
• get_file(guest → local)
  This unlocks “return results” (artifacts) without network.

4. Health + metadata

• health
• get_system_info (kernel version, disk space, mem/cpu)
• shutdown

[aniketmaurya]

@codex please review this issue and based on the codebase please create an implementation plan

[chatgpt-codex-connector]

Summary

• Added a new implementation-planning document that reviews current SmolVM integration points and identifies architecture gaps for a vsock control plane (vm.py startup path, api.py Firecracker client, facade.py user API, build.py image customization, and types.py model extensions). docs-vsock-control-plane-implementation-plan.mdL1-L19
• Defined a phased delivery plan (MVP, recommended, hardening) covering exec, streaming, cancellation, health/system metadata, and optional file transfer over vsock. docs-vsock-control-plane-implementation-plan.mdL20-L41
• Added a concrete 7-step implementation roadmap with proposed file touchpoints, acceptance criteria, security controls, testing/CI expectations, risks, and definition-of-done to make execution on top of the original PR actionable. docs-vsock-control-plane-implementation-plan.mdL42-L186
• Committed the change (docs: add vsock control plane implementation plan) and created a follow-up PR using the make_pr tool.

Testing

• ⚠️ python - <<'PY' ... requests.get('https://duckduckgo.com/html/?q=Firecracker+vsock+best+practices+request+response+protocol') ... PY (failed due to proxy restriction: Tunnel connection failed: 403 Forbidden).
• ❌ pytest -q tests/test_types.py (fails in this environment without package path setup: ModuleNotFoundError: No module named 'smolvm').
• ✅ PYTHONPATH=src pytest -q tests/test_types.py (passes: 22 tests).

View task →