Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Docs: cover microvm sandbox support for kagent 1.x

Abierto
  • ¿Algo no está bien?
#537 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
helm, kubernetes
Área
devops, documentation, infrastructure

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
TypeScript
Estrellas
20
Forks
66
Merge medio
1 d 2 h
PR fusionados (30 d)
49

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de kagent-dev/website

Todos los issues de kagent-dev/website

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.