Add guest init binary, hooks, and wiring for go-microvm runtime

[JAORMX]

The go-microvm runtime skeleton was solid but couldn't boot MCP server
images because it lacked guest-side infrastructure. go-microvm uses
gvproxy networking (virtio-net), so the guest must configure its own
network via DHCP — libkrun's built-in init doesn't do this.

This adds:

• thv-vm-init: PID 1 guest binary that boots (mounts, DHCP, SSH via
  go-microvm/guest/boot), reads /etc/thv-entrypoint.json for the original
  OCI cmd/env/workdir, execs the MCP server as a child, forwards
  signals, and halts the VM cleanly on exit
• RootFS hooks: InjectInitBinary (embeds compiled binary),
  InjectEntrypoint (captures OCI config before init override),
  InjectEntrypointOverride (explicit command), InjectSSHKeys
• libkrun backend with WithUserNamespaceUID(1000,1000) for virtiofs
  passthrough, WithCleanDataDir, WithLogLevel, WithImageCache
• HTTP readiness probe (exponential backoff, accepts any response)
• Recovered VM lifecycle fix: StopWorkload/RemoveWorkload now kill
  orphaned runner processes for VMs without handles
• Build infrastructure: build-vm-init task with CGO_ENABLED=0 GOOS=linux,
  wired as dependency of the main build task

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.

[jhrozek]

Code Review Notes

Nice work on the go-microvm runtime skeleton — the architecture is clean, the init binary design is elegant, and the test coverage for hooks/permissions/state/lifecycle is solid. A few things I noticed that are worth discussing:

---

1. VirtioFS mounts silently drop ReadOnly flag

buildVirtioFSMounts in permissions.go:55-71 only copies Tag and HostPath from runtime.Mount — the ReadOnly field is never propagated. This means --volume /path:/path:ro mounts become read-write inside the guest VM.

I checked upstream and VirtioFSMount in go-microvm v0.0.23 only has Tag and HostPath fields, so this can't be fixed on the ToolHive side alone. Would adding a ReadOnly field to VirtioFSMount (and plumbing it through hypervisor.FilesystemMount) be feasible upstream?

In the meantime, it might be worth either logging a warning when read-only mounts are requested, or rejecting them with a clear error so users aren't silently getting weaker isolation than they expect.

No catalog entries currently use read mounts, so this is low practical impact today — but it's a correctness gap relative to how Docker handles the same permission profile.

2. doc.go has wrong runtime name

doc.go:9 says TOOLHIVE_RUNTIME=microvm but register.go:13 defines RuntimeName = "go-microvm".

3. Egress policy: empty AllowHost + InsecureAllowAll=false = unrestricted

buildEgressPolicy in permissions.go:28-29 returns nil (no policy = unrestricted) when AllowHost is empty, even when InsecureAllowAll is false. The intent of that configuration is deny-all, but the VM gets full network access.

Removing the len(out.AllowHost) == 0 early return would fix this — but it depends on whether go-microvm treats an empty AllowedHosts slice as deny-all. Worth verifying upstream.

4. Toolhive runtime env vars don't reach the child MCP server process

This one is more significant than it looks on the surface. In main.go:58:

cmd.Env = append(os.Environ(), ep.Env...)

The Toolhive runtime vars (MCP_TRANSPORT, MCP_PORT, API keys, egress proxy settings) are written to /etc/environment by the InjectEnvFile hook. However, boot.Run loads that file but only passes the vars to the SSH server config — it does not call os.Setenv. So os.Environ() inside the init binary contains only PATH + OCI image ENV (via .krun_config.json), and ep.Env is also OCI image ENV (captured from the image config). The Toolhive runtime vars are absent from the child process entirely.

The init binary likely needs to load /etc/environment itself and layer the env correctly:

• OCI image ENV as the base (defaults)
• Toolhive runtime vars on top (overrides, matching Docker's convention where runtime > image)

5. SSH private key persists on disk after VM stop

GenerateKeyPair in deploy.go:117 writes a private key to vmDir. Only RemoveWorkload cleans up data dirs — StopWorkload does not. Since the comment says "we don't actively SSH into the guest," the private key could be deleted immediately after reading the public key content.

6. Minor: deploy.go:55 uses fmt.Sprintf for path construction

vmDir := fmt.Sprintf("%s/vms/%s", c.opts.dataDir, name)

Should be filepath.Join(c.opts.dataDir, "vms", name) for defense-in-depth (upstream sanitization handles it today, but filepath.Join is the idiomatic approach).

In general, the fix is to ensure that paths derived from archive entry names cannot escape the intended extraction directory. This is best done by: (1) normalizing the entry name, (2) rejecting absolute paths, (3) rejecting any path that contains ".." components (not just a leading ".."), and (4) verifying that the final path, after joining with the destination directory, still resides within that directory.

In this codebase, the right place to enforce this is safeTarEntryPath, which already centralizes path validation. We can harden it without changing the behavior for valid entries by:

• After filepath.Clean, splitting the cleaned name into path components and rejecting any component equal to ".." or "." (or that is empty).
• Keeping the existing checks for absolute paths.
• Keeping (or slightly tightening) the check that the joined targetPath is within destDir.

No other call sites need to change, because all extraction goes through safeTarEntryPath. The additional logic will ensure that targetPath can no longer be tainted by any .. segments in the tar header, fully addressing the three variants CodeQL reported.

Concretely, in pkg/container/gomicrovm/firmware.go:

• Modify safeTarEntryPath (lines 502–515) to:
  • Reject names whose cleaned form is ".".
  • Split cleanName on filepath.Separator and reject if any component is ".." or "." or empty.
  • Keep the filepath.IsAbs and final HasPrefix checks.

No new imports are needed; strings and filepath are already imported.

---

[codecov]

Codecov Report

❌ Patch coverage is 37.63066% with 716 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.39%. Comparing base (a948281) to head (a0c6a6a).

Files with missing lines	Patch %	Lines
pkg/container/gomicrovm/firmware.go	0.00%	361 Missing ⚠️
pkg/container/gomicrovm/deploy.go	5.92%	143 Missing ⚠️
cmd/thv-vm-init/main.go	7.31%	76 Missing ⚠️
pkg/container/gomicrovm/client.go	28.30%	36 Missing and 2 partials ⚠️
pkg/container/gomicrovm/autodetect.go	0.00%	26 Missing ⚠️
cmd/thv-vm-init/stdiorelay.go	77.46%	10 Missing and 6 partials ⚠️
pkg/container/gomicrovm/readiness.go	77.27%	5 Missing and 5 partials ⚠️
pkg/container/gomicrovm/lifecycle.go	90.81%	6 Missing and 3 partials ⚠️
pkg/container/gomicrovm/hooks.go	84.31%	4 Missing and 4 partials ⚠️
pkg/container/gomicrovm/state.go	89.87%	6 Missing and 2 partials ⚠️
... and 7 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4358      +/-   ##
==========================================
- Coverage   69.02%   68.39%   -0.63%     
==========================================
  Files         502      520      +18     
  Lines       52008    53155    +1147     
==========================================
+ Hits        35899    36357     +458     
- Misses      13320    13984     +664     
- Partials     2789     2814      +25     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.