docs: pin and document the supported agent-sandbox-controller version

[dimityrmirchev]

Description

OpenShell depends on the upstream kubernetes-sigs/agent-sandbox controller (ASC) to run sandbox pods on Kubernetes, but the supported version is neither up-to-date nor documented. There are two related problems:

1. The vendored manifest pins an early controller release

deploy/kube/manifests/agent-sandbox.yaml:75 pins:

image: registry.k8s.io/agent-sandbox/agent-sandbox-controller:v0.1.0

Upstream release history (as of filing):

Version	Released
v0.4.6	2026-05-14 (latest)
v0.4.5	2026-05-06
v0.4.3	2026-04-28
v0.4.2	2026-04-22
v0.3.10	2026-04-08
v0.2.1	2026-03-14
v0.1.1	2026-02-04
v0.1.0	2025-11-07 ← pinned here

The pinned version pre-dates several months of upstream fixes and features. It would be worth confirming whether this is intentional (e.g. the newer releases haven't been validated yet) or simply hasn't been refreshed.

2. The supported version is undefined and the install paths disagree

There is no documented support matrix — nothing in the repo states which ASC versions OpenShell's Kubernetes driver is compatible with, what CRD schema (agents.x-k8s.io/v1alpha1) revision is required, or when the vendored manifest was last refreshed.

The three install paths are also inconsistent:

Path	Source	What it installs
e2e tests	e2e/with-kube-gateway.sh:529 applies deploy/kube/manifests/agent-sandbox.yaml	Pinned v0.1.0
Local Helm/k3s dev	tasks/scripts/helm-k3s-local.sh:138 applies the same vendored manifest	Pinned v0.1.0
User-facing docs	docs/kubernetes/setup.mdx:36-37 instructs kubectl apply -f .../releases/latest/download/manifest.yaml	latest (currently v0.4.6)
Helm chart README	deploy/helm/openshell/README.md:17 instructs .../releases/latest/download/manifest.yaml	latest

A user following the published docs may end up running a different controller version than the one OpenShell's e2e suite exercises, which makes it harder to reason about whether a given combination is supported.

Proposed Resolution

1. Pick a supported version (or range). Decide whether OpenShell pins to a specific tested ASC version or supports a documented range. Refresh the vendored deploy/kube/manifests/agent-sandbox.yaml accordingly.
2. Document the support matrix. Add a section to docs/kubernetes/setup.mdx (and/or architecture/) stating the supported ASC version(s), the required CRD API version, and how to upgrade in lockstep with OpenShell releases.
3. Align install paths. Either pin all three paths to the same tested version, or document explicitly why e2e uses a vendored copy while users install latest (and consider CI that flags drift).
4. Add a refresh process. Consider a periodic check (or Renovate/Dependabot-style automation) that surfaces new ASC releases against the vendored manifest, similar to how other vendored upstream dependencies are tracked.

Context

• Vendored manifest: deploy/kube/manifests/agent-sandbox.yaml (single file containing namespace, RBAC, StatefulSet, and the sandboxes.agents.x-k8s.io CRD)
• Upstream project: https://github.com/kubernetes-sigs/agent-sandbox
• Existing user-facing docs: docs/kubernetes/setup.mdx, docs/kubernetes/openshift.mdx, docs/reference/sandbox-compute-drivers.mdx — none of these mention a version requirement.

Agent Investigation

Searched the repo for all agent-sandbox references. The only place the controller version is expressed is the image tag in deploy/kube/manifests/agent-sandbox.yaml:75. No Cargo.toml, go.mod, Helm chart, or architecture doc references an ASC version constraint. No existing open or closed issue tracks this (searched agent-sandbox-controller in:title,body).