NVIDIA / NVIDIA/OpenShell

feat(agents): support Kubernetes-driver gateways in the agent launcher

Open
#3,469 1 comment 0 reactions 1 assignee View on GitHub

@purp is already working on this.

Since Sep 18, 2026.

Dominant language
Rust
Stars
8.7k
Forks
1.3k
Avg merge
2d 11h
Merged PRs (30d)
253

Description

User Story

As a maintainer running a persistent Kubernetes-backed gateway, I want scripts/agents/run.sh to launch agents against that gateway, so that unattended agents such as gator run on the same deployment topology used for shared and cloud deployments instead of requiring a separate Docker gateway kept alive just for them.

Problem Statement

The agent launcher supports only Docker and Podman compute drivers. Two gates combine to block Kubernetes:

  • scripts/agents/run.sh:695 rejects any other driver outright: agent launcher local image builds require Docker or Podman.
  • scripts/agents/run.sh:630 requires a local Dockerfile source, because the immutable agent payload (skills, prompts) is baked in as appended COPY layers. --from therefore cannot point at a pre-built registry image to bypass the build.

Together these mean no agent defined under scripts/agents/ can be launched against a gateway using the Kubernetes compute driver. The launcher builds into the local engine's image store, and nothing makes that image resolvable by a cluster.

Impact / Why This Matters

Kubernetes is the documented topology for running the gateway on a shared cluster, in a cloud environment, or as team infrastructure. A maintainer who runs the gateway that way must stand up and maintain a second, Docker-driver gateway whose only purpose is hosting agents.

For an unattended agent like gator, that second gateway becomes availability-critical infrastructure — typically on a developer workstation, since that is where the Docker driver is convenient. The workaround is insufficient on two counts: it does not survive the move to a real cluster, and it means agents are only ever exercised on a topology different from the one the project documents for production.

Proposed Design

run.sh should accept a gateway whose compute driver is Kubernetes. After building the payload image locally, the launcher makes that image resolvable by the target cluster and passes the resulting reference to the sandbox.

Observable behavior:

  • ./scripts/agents/run.sh --agent <id> --gateway <kubernetes-gateway> ... provisions the sandbox and starts the agent, with the same supervised/watch semantics as the Docker path.
  • How the image reaches the cluster is configurable, because a local single-node cluster and a remote managed cluster need different answers (importing into the node image store versus pushing to a registry the cluster can pull from).
  • When no image destination is configured, the launcher fails with a message naming the missing configuration and how to supply it, rather than rejecting the driver outright.
  • Payload immutability is preserved: skills and prompts remain baked into the image and read-only.

Acceptance Criteria

  • The launcher provisions an agent sandbox against a Kubernetes-driver gateway.
  • The agent payload remains baked into the image and read-only, matching the Docker path.
  • The image destination is configurable to cover both a local cluster and a remote registry.
  • A missing or unreachable image destination produces an actionable error naming the required configuration.
  • Docker and Podman launches are unchanged.
  • skills/ and the launch-openshell-gator contributor skill document the Kubernetes path.

Alternatives Considered

  • Publish a pre-built agent image and point --from at it. Rejected by the immutable-payload requirement at run.sh:630, and it would decouple the payload from the image build that currently guarantees it is present and read-only.
  • Keep a dedicated Docker-driver gateway for agents. The current workaround. It duplicates infrastructure, does not transfer to a cluster deployment, and leaves agents untested on the documented production topology.
  • Have the gateway build images on behalf of the launcher. Expands gateway responsibility and trust surface well beyond its current role for a build-time convenience.

Agent Investigation

  • scripts/agents/run.sh:683-698 resolves the gateway's compute driver via gateway info --output json, requires exactly one driver, and accepts only docker or podman.
  • scripts/agents/run.sh:623-630 enforces that --from names a local Dockerfile or directory, because the payload is appended to the staged Dockerfile as COPY layers before the build.
  • scripts/agents/gator/agent.yaml uses from: agent://., so gator specifically takes the local-build path.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.