feat(agents): support Kubernetes-driver gateways in the agent launcher
@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:695rejects any other driver outright:agent launcher local image builds require Docker or Podman.scripts/agents/run.sh:630requires a local Dockerfile source, because the immutable agent payload (skills, prompts) is baked in as appendedCOPYlayers.--fromtherefore 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 thelaunch-openshell-gatorcontributor skill document the Kubernetes path.
Alternatives Considered
- Publish a pre-built agent image and point
--fromat it. Rejected by the immutable-payload requirement atrun.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-698resolves the gateway's compute driver viagateway info --output json, requires exactly one driver, and accepts onlydockerorpodman.scripts/agents/run.sh:623-630enforces that--fromnames a local Dockerfile or directory, because the payload is appended to the staged Dockerfile asCOPYlayers before the build.scripts/agents/gator/agent.yamlusesfrom: agent://., so gator specifically takes the local-build path.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.