Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Docs: cover microvm sandbox support for kagent 1.x

Aperta
  • Qualcosa non va?
#537 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
helm, kubernetes
Ambito
devops, documentation, infrastructure

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
TypeScript
Stelle
20
Fork
66
Merge medio
1g 2h
PR unite (30g)
49

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di kagent-dev/website

Tutte le issue di kagent-dev/website

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.