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

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

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.
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.
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).
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).

chore(k8s): use upstream agent-sandbox manifests in CI/e2e, install e…

chore(k8s): use upstream agent-sandbox manifest in CI/e2e

chore(k8s): use upstream agent-sandbox manifest in CI/e2e (#1657)

Adding a concrete, now-active breakage caused by exactly this gap.

Since this was filed, agent-sandbox v0.5.0 (2026-06-24) introduced agents.x-k8s.io/v1beta1 and made the controller stamp v1beta1 ownerReferences on sandbox pods. The user-facing docs (docs/kubernetes/setup.mdx) and the Helm README both instruct kubectl apply -f .../releases/latest/download/manifest.yaml, so following the docs today installs v0.5.0 — which breaks sandbox execution at runtime, not just "undocumented".

Mechanism

The gateway hardcodes the expected Sandbox ownerReference API version in the bootstrap authenticator:

crates/openshell-server/src/auth/k8s_sa.rs
  const SANDBOX_API_GROUP:        "agents.x-k8s.io";
  const SANDBOX_API_VERSION:      "v1alpha1";
  const SANDBOX_API_VERSION_FULL: "agents.x-k8s.io/v1alpha1";

During IssueSandboxToken, k8s_sa validates the projected SA token via TokenReview (succeeds), then verifies the pod's owning Sandbox CR / ownerReference against v1alpha1. With the v0.5.0 controller the pod ownerRef is agents.x-k8s.io/v1beta1, so the check fails and the RPC returns an error after TokenReview. The supervisor never gets a gateway JWT, loops the bootstrap forever, and the agent container crashloops:

WARN openshell_sandbox: Policy fetch failed, retrying
Error: × Policy fetch failed after 5 attempts: IssueSandboxToken bootstrap exchange failed

Note the v0.5.0 CRD still serves v1alpha1 (deprecated), so a GET at v1alpha1 works — but the ownerReference string the controller writes is v1beta1, which is what the gateway compares against. So "v1alpha1 still served" is not sufficient; the controller's stamped ownerRef version is what matters.

Environment

Gateway: 0.0.70-dev.1 (helm-chart dev), Kubernetes driver, single-node Talos cluster.
Symptom disappears entirely after pinning the controller down.

Workaround (confirmed fix)

Pin agent-sandbox to v0.4.6 (last release that ships only v1alpha1). After downgrading, the gateway logs issued gateway sandbox JWT, the sandbox reaches Ready with 0 restarts, and sandbox exec relays output normally.

Suggestion

Until the K8s driver / k8s_sa supports agents.x-k8s.io/v1beta1 ownerReferences, it'd help to:

Update the docs + Helm README to pin a specific agent-sandbox tag (v0.4.6) rather than latest, and
Add a startup/log warning when the gateway encounters a Sandbox ownerReference whose apiVersion ≠ the expected SANDBOX_API_VERSION (today it fails silently from the gateway's logs — only the sandbox-side "bootstrap exchange failed" is visible).

@pziecina

@pziecina OpenShell now supports v1beta1 per #2009 and #2013

@dimityrmirchev

@dimityrmirchev we no longer vendor the agent-sandbox manifests, and instead now test the last release of agent-sandbox that included only the v1alpha1 CRD version in CI (0.4.6), and also test v1beta1 as well in CI in a matrix.

I think it makes sense that we keep support for both versions while things are moving fast, and plan to support the latest versions of agent-sandbox as they become available on the kube driver. The install paths now should generally follow latest.

I'll go ahead and close this issue. Please let me know if there's any questions!

Navigation Menu

Repository navigation

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

Description

1. The vendored manifest pins an early controller release

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

Proposed Resolution

Context

Agent Investigation

Mechanism

Environment

Workaround (confirmed fix)

Suggestion

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Description

1. The vendored manifest pins an early controller release

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

Proposed Resolution

Context

Agent Investigation

Activity

pziecina commented on Jun 25, 2026

Mechanism

Environment

Workaround (confirmed fix)

Suggestion

TaylorMutch commented on Jun 26, 2026

TaylorMutch commented on Jun 26, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions