docs: add Firecracker microVM isolation guide

[chaodu-agent]

Closes #736

What

Adds docs/firecracker.md — a guide for running OpenAB agents inside Firecracker microVMs via Kata Containers on K3s.

Why

OpenAB's current sandbox uses K8s pod isolation (shared kernel). Firecracker provides microVM isolation (independent kernel per agent) — the strongest boundary available. This is relevant for users who want defense against kernel exploits.

Content

• Prerequisites (x86_64 + KVM, Intel N100 confirmed)
• Install Kata Containers on K3s via kata-deploy (K3s-specific overlay)
• Verification steps
• OAB Helm config: podRuntimeClassName: kata-fc
• Resource overhead on N100 (~30-50MB per microVM)
• Limitations (no GPU, block storage only)
• Comparison table: runc vs kata-fc vs kata-qemu
• Uninstall instructions

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: docs: add Firecracker microVM isolation guide
• Source: docs: add Firecracker microVM isolation guide #737
• Status: moved to PR-Screening
• Generated at: 2026-05-05T00:01:53.408Z
• Discord thread: https://discord.com/channels/1488041051187974246/1501010780768702615

Screening report

## Intent

PR #737 adds documentation for running OpenAB agents with Firecracker microVM isolation through Kata Containers on K3s.

The operator-visible problem is that OpenAB’s current Kubernetes pod sandbox shares the host kernel. For deployments running untrusted or higher-risk agent workloads, that leaves a meaningful isolation gap. The guide aims to document a stronger runtime boundary where each agent pod can run inside a microVM with its own kernel.

Feat

This is a docs improvement.

Behaviorally, it does not change OpenAB code. It adds docs/firecracker.md, covering prerequisites, Kata Containers setup on K3s, verification, Helm configuration via podRuntimeClassName: kata-fc, expected resource overhead, limitations, runtime comparison, and uninstall steps.

Who It Serves

Primary beneficiaries:

• Deployers running OpenAB in Kubernetes/K3s
• Agent runtime operators handling untrusted workloads
• Security-conscious maintainers evaluating stronger isolation options

Secondary beneficiaries:

• Reviewers who need a documented deployment path for Firecracker-backed agent isolation

Rewritten Prompt

Add a deployment guide at docs/firecracker.md explaining how to run OpenAB agent pods with Firecracker microVM isolation using Kata Containers on K3s.

The guide should include:

• Supported host assumptions and prerequisites, including KVM and architecture constraints
• K3s-specific Kata installation steps using kata-deploy
• Verification commands proving kata-fc is available and usable
• OpenAB Helm configuration using podRuntimeClassName: kata-fc
• Operational tradeoffs, including memory overhead, startup latency expectations, storage/network limitations, and lack of GPU support
• A concise comparison of runc, kata-fc, and kata-qemu
• Rollback or uninstall instructions

Keep the guide explicit that this is an optional hardening path, not the default runtime requirement. Avoid overstating security guarantees; describe Firecracker as reducing shared-kernel risk by moving workloads into microVMs.

Merge Pitch

This is worth advancing because it documents a practical hardening path for operators who need stronger isolation than standard Kubernetes pods. It also gives reviewers and future deployers a concrete reference instead of leaving Firecracker support as tribal knowledge.

Risk profile is low because the PR is documentation-only. The main reviewer concern should be accuracy: whether the K3s/Kata commands are current, whether kata-fc is the correct runtime class in the documented setup, and whether the security claims are carefully scoped.

Best-Practice Comparison

OpenClaw principles that are relevant:

• Isolated executions: Highly relevant. The guide directly addresses stronger workload isolation.
• Explicit delivery routing: Not directly relevant unless runtime class selection is treated as scheduling/routing policy.
• Durable job persistence: Not relevant to this docs-only runtime isolation guide.
• Retry/backoff and run logs: Not relevant unless OpenAB later documents observability differences under microVM runtimes.
• Gateway-owned scheduling: Partially relevant if OpenAB eventually chooses runtime class per job or trust level.

Hermes Agent principles that are relevant:

• Fresh session per scheduled run: Conceptually related. Firecracker isolation supports cleaner execution boundaries.
• Self-contained prompts for scheduled tasks: Not relevant.
• Gateway daemon tick model: Not relevant.
• File locking to prevent overlap: Not relevant.
• Atomic writes for persisted state: Not relevant.

The strongest comparison point is isolated execution. This PR aligns with the direction of treating agent execution as a security-sensitive runtime concern, but it does not implement scheduling, persistence, locking, or run lifecycle behavior.

Implementation Options

Option 1: Conservative docs-only merge
Merge the guide after validating commands, runtime class names, and security wording. Keep it clearly marked as optional deployment hardening.

Option 2: Balanced docs plus config example
Keep the guide, but also add a small example Helm values file or documented snippet showing how to set podRuntimeClassName: kata-fc for agent workloads specifically. This makes the docs easier to apply and easier to test.

Option 3: Ambitious runtime isolation profile
Introduce first-class OpenAB deployment profiles for sandbox runtimes, such as runc, kata-fc, and possibly kata-qemu. This could include Helm values, validation notes, and future scheduling policy for assigning runtimes based on workload trust level.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative docs-only merge	High	Low	Medium	High	Medium	Strong
Docs plus config example	Medium	Low-Medium	High	High	High	Strongest
Runtime isolation profiles	Low	High	High if done well	Medium	High	Premature unless runtime policy work is already planned

Recommendation

Advance the PR with the balanced option if the existing Helm surface supports it cleanly: keep docs/firecracker.md, verify the commands and claims, and add or tighten a concrete Helm values example for podRuntimeClassName: kata-fc.

That gives Masami or Pahud a mergeable next step with low code risk and high operator value. Defer first-class runtime profiles or trust-based scheduling to a separate follow-up issue, since that would move beyond documentation into runtime policy design.

[masami-agent]

PR Review: #737

Reviewed commit: 6140f77

Summary

• Problem: Document how to run OpenAB agents in Firecracker microVMs for kernel-level isolation.
• Approach: New standalone doc (docs/firecracker.md) covering Kata Containers + Firecracker on K3s.
• Risk level: Medium — the doc contains Helm instructions that reference a non-existent chart value.

Core Assessment

1. Problem clearly stated: ✅ (linked issue docs: add docs/firecracker.md — Kata Containers + Firecracker microVM isolation #736, clear motivation)
2. Approach appropriate: ⚠️ (good doc structure, but Helm integration section is factually incorrect)
3. Alternatives considered: N/A (docs PR)
4. Best approach for now: ❌ (doc will mislead users — see 🔴 below)

---

Review Summary (Traffic Light)

🔴 Critical: podRuntimeClassName does not exist in the Helm chart

Where: docs/firecracker.md lines 60–75 ("Configure OpenAB to Use Firecracker" section)

What's wrong: The doc instructs users to run:

helm install openab ... --set podRuntimeClassName=kata-fc

and shows a values file with podRuntimeClassName: kata-fc.

However, the OpenAB Helm chart (charts/openab/values.yaml) has no podRuntimeClassName field, and the deployment template (charts/openab/templates/deployment.yaml) does not render spec.template.spec.runtimeClassName.

Why it matters: Helm silently ignores unknown values. Users following this guide would get a successful helm install but their pods would still run on the default runtime (runc) — not Firecracker. The promised isolation would not be delivered, with no error to indicate the failure. This is a silent security gap.

Fix options (pick one):

1. Pair this doc with a chart PR that adds podRuntimeClassName support to values.yaml and renders it in deployment.yaml. Then this doc becomes accurate.
2. Change the doc to use kubectl patch or a post-install step that sets runtimeClassName on the deployment directly, making it independent of chart support.
3. Change the doc to recommend a values override file with extraPodSpec or similar — but this also doesn't exist in the chart today.

Option 1 is the cleanest path. The chart change is small (~3 lines: one in values.yaml, one conditional block in deployment.yaml).

---

🟡 Minor: Helm install command uses wrong chart reference

Where: docs/firecracker.md line 62

What's wrong: The doc shows:

helm install openab openab/openab \

This implies a Helm repo named openab has been added. The OpenAB chart is distributed via OCI registry, not a classic Helm repo.

Fix: Use the OCI reference:

helm install openab oci://ghcr.io/openabdev/charts/openab \

---

🟢 Info

• The Kata Containers installation steps, verification procedure, comparison table, and resource overhead estimates are well-written and accurate.
• Good scope discipline — single file, focused topic.
• Commit message follows Conventional Commits.

Verdict

REQUEST_CHANGES — The 🔴 Critical must be resolved. The doc's core value proposition (Firecracker isolation via Helm) does not work with the current chart. Either the chart needs to be updated first (separate PR), or the doc needs to use a different mechanism to set runtimeClassName.