Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Docs: cover microvm sandbox support for kagent 1.x

オープン
  • 何か問題がありますか？
#537 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
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日 2時間
マージ済み PR（30日）
49

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

kagent-dev/website のほかの issue

kagent-dev/website の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。