Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Docs: cover microvm sandbox support for kagent 1.x

Đang mở
  • Có gì không ổn?
#537 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
45/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
helm, kubernetes
Lĩnh vực
devops, documentation, infrastructure

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
TypeScript
Star
20
Fork
66
Merge trung bình
1 ngày 2 giờ
Pull request đã merge (30 ngày)
49

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của kagent-dev/website

Tất cả issue của kagent-dev/website

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.