Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Docs: cover microvm sandbox support for kagent 1.x

未关闭
  • 哪里不对？
#537 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

@boxcee-interview 已经在做这个了。

开始于 2026年10月8日。

  • #570 来自 @boxcee-interview —— 未关闭

评估

难度
4/5
预计耗时
3-5 天
新手友好度
45/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
helm, kubernetes
领域
devops, documentation, infrastructure

调研方向

Start with operations/tune-agent-substrate.md, substrate-runtime/sandboxing.md, and docs/architecture/configuration-and-compilation.md under WorkerPool sandbox selection. Verify the documented class mapping, prerequisites, Helm value pairing, revision and snapshot behavior, and failure status on a live cluster running both classes; done means both outdated claims are corrected and all checklist items are verified.

由索引模型根据 Issue 内容生成。

描述

help wanted

Three places tell a reader that a microvm WorkerPool cannot run kagent agents. kagent#2918 made it work in 1.0.0-alpha4, so the docs have steered readers away from a supported configuration for several releases.

Verified against v1.0.0-alpha7 on 2026-10-06. All three claims are still live word for word. This is a correction to existing pages, not a new page. Part of #549.

The false claims

Location Text to remove
operations/tune-agent-substrate.md:10 "Leave the sandbox class on gvisor. A pool set to any other class sits idle while turns time out."
operations/tune-agent-substrate.md:182 The Keep pools on the gvisor class section: "Workers in a microvm pool accept no kagent Actor, and the pool sits idle while turns time out."
substrate-runtime/sandboxing.md:36 "kagent generates ActorTemplates that use the gvisor class. Keep a WorkerPool that backs kagent Harnesses on gvisor."
data/glossary.yaml:138 The gVisor entry: "kagent compiles every ActorTemplate to the gvisor sandbox class." This tooltip renders on every page that glosses the term.

A fourth spot needs generalizing rather than deleting: tune-agent-substrate.md:195 says a SandboxConfig named gvisor-default must exist "because kagent names it directly rather than resolving a default". That reasoning still holds, but it applies per class.

What the controller actually does

The pool's spec.sandboxClass selects the ActorTemplate's sandbox configuration, read from sandboxConfigForClass in go/core/internal/substrate/actor_template.go:

WorkerPool sandboxClass Sandbox class SandboxConfig name
Empty or gvisor SANDBOX_CLASS_GVISOR gvisor-default
microvm SANDBOX_CLASS_MICROVM microvm

Substrate requires an explicit name and rejects a missing SandboxConfig or a class mismatch. These are not API defaults or discovery.

What a writer gets wrong here

  • Selecting microvm installs nothing. The operator installs the matching cluster-scoped SandboxConfig and provisions KVM-capable Workers and the runtime assets (cloud-hypervisor, kata-kernel, kata-image, already covered in sandboxing.md). kagent configures no RuntimeClass and fetches no assets.
  • The image must pair with the class. substrateWorkerPool.sandboxClass needs a matching substrateWorkerPool.workerImage (ateom-gvisor or ateom-microvm), alongside controller.substrate.enabled. Pairing microvm with a gVisor image is the likeliest mistake.
  • The class is part of revision identity. Switching a pool between classes produces a distinct ActorTemplate and its own golden snapshot. Empty and explicit gvisor hash the same, so returning to gVisor restores the original digest. Existing Sessions stay pinned to the revision they started on.
  • Failures are reported, not silent. An unsupported class sets the Compatible condition to RevisionInvalid with unsupported sandbox class "<value>"; a missing pool reports WorkerPoolNotFound. Neither idles. This replaces the "sits idle while turns time out" symptom.
  • The class alone is not parity with gVisor. Upstream's configuration-and-compilation.md notes that lifecycle and cross-node restore also depend on Agent Substrate, the runtime images, and worker hardware.

This issue covers the WorkerPool sandbox class only. For standalone sandboxes, link to substrate-runtime/standalone-sandboxes.md rather than re-explaining them.

Before starting

This needs a live cluster with the microvm prerequisites, which is the hard part rather than the writing. Test on alpha6 or later: kagent#3004 added Cloud Hypervisor to the E2E lanes and fixed a SQLITE_READONLY_DBMOVED failure on first message after a micro-VM restore. Read docs/architecture/configuration-and-compilation.md under WorkerPool sandbox selection, run an agent on a microvm pool end to end, then switch the pool's class and observe the revision, the snapshot, and what a misconfigured pool reports.

Done when

  • All four locations above are corrected, including the glossary tooltip.
  • The class-to-SandboxConfig mapping is documented, with gvisor named as the default.
  • The operator prerequisites are stated, including that kagent installs none of them.
  • The image-to-class pairing is stated alongside sandboxClass.
  • Revision identity and snapshot behavior on a class switch are covered.
  • The named failure reasons replace the "sits idle" symptom.
  • Every claim was verified on a cluster running both classes.
主要语言
TypeScript
星标
20
派生
66
平均合并
1 天 3 小时
30 天内合并 PR
52

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

kagent-dev/website 的其他 Issue

查看 kagent-dev/website 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。