[bpmct]

Description

Adds a coder-labs template that runs each workspace in an agent-sandbox Sandbox. You and your AI agent share one sandbox.

• Kernel isolation: gVisor by default, or a Kata microVM (QEMU or Cloud Hypervisor).
• Network isolation: a NetworkPolicy per profile: Fully isolated (default, Coder only), GitHub only, or Public internet.
• Home: persistent (a disk, with a prebuilt preset per profile) or scratch (claimed from a SandboxWarmPool, deleted on stop, for Fully isolated and GitHub only).
• Image: build/Dockerfile bakes in the Coder agent, code-server, and Claude Code, so a start downloads nothing. Users build it themselves.
• Cluster setup: cluster/ is a Terraform configuration that creates the namespace, RBAC, a SandboxTemplate and warm pool per runtime and profile, and an optional EKS guardrail. Its coder_variables output is the --variables-file for coder templates push, so the template and pools agree.
• README: why agent-sandbox, startup speed with a real-time demo GIF, agent-sandbox vs Pods and when each fits, firewall options (NetworkPolicy, ClusterNetworkPolicy, Cilium, a proxy), and ingress options. No parameter or variable tables, since the registry shows them.
• Icon: .icons/agent-sandbox.svg, the agent-sandbox logo (Apache-2.0) in the project's purple.

Startup on EKS, create to connected agent: 3.5 to 6.5 s from a warm pool, 4 to 7 s from a prebuild, about 17 s cold on gVisor.

Type of Change

• New module
• New template
• Bug fix
• Feature/enhancement
• Documentation
• Other

Template Information

Path: registry/coder-labs/templates/kubernetes-agent-sandbox

Testing & Validation

• Tests pass locally (terraform test: 36 template runs and 18 cluster/ runs, with mock providers). CI runs .tftest.hcl only for modules, so these do not run in CI.
• Code formatted (bun fmt:ci, terraform fmt)
• Changes tested locally (EKS with agent-sandbox v1.0.4, gVisor release-20261102.0, Kata, VPC CNI v1.22.4)

Live test results

Case	Agent ready
Scratch home from a warm pool	3.5 to 6.5 s
Persistent home from a prebuild	4 to 7 s
Persistent home, cold, gVisor / Kata QEMU	about 17 s / 19 s
Persistent home, cold, with a coder/coder clone	about 58 s

• Fully isolated: only Coder is reachable. DNS, GitHub, public IPs, cloud metadata, the API server, and other Pods are blocked.
• GitHub only: GitHub works by name and by IP. Everything else is blocked.
• Public internet: ports 80 and 443 are open. Private ranges, metadata, and the cluster are blocked.
• Policy check: the agent starts only after the NetworkPolicy is in force, and re-checks every 5 s. When I deleted a workspace's NetworkPolicy, the agent stopped about 5 s later.
• Web terminal on gVisor: gVisor before release-20261019.0 blocks on a zero-length write to a PTY master, which the agent does on every resize, so the terminal took no input. Fixed upstream in google/gvisor@6b4e208e4. The README requires that release or later. Verified with the stock agent's write path on old and new runsc.
• After the review fixes: all four preset types (Fully isolated and GitHub only, scratch and persistent) connected, the agent was PID 1 under bash, the web terminal took input, and the profiles blocked and allowed as expected.
• Not tested live: Kata Cloud Hypervisor, and GKE.

Plan and decisions

• Why a second Terraform root in cluster/: warm pools, SandboxTemplates, and RBAC are cluster objects that an administrator owns, not per-workspace objects, so the template cannot create them. A Terraform root keeps the admin setup in the same language as the template, and its coder_variables output keeps both in line.
• Provider: hashicorp/kubernetes for both the template and cluster/. kubernetes_manifest reads CRD schemas at plan time, so the provisioner needs CRD read access. cluster/ sets force_conflicts so it can take over objects created with kubectl.
• Defaults: gVisor is the default runtime because it works on normal nodes. Presets are the default, and each persistent preset has prebuild_instances prebuilds.
• Two homes: scratch uses warm pools. Persistent uses prebuilds, because a SandboxClaim cannot carry a disk or be suspended yet (Feature Request: Support volumeClaimTemplates in SandboxTemplate / SandboxClaim kubernetes-sigs/agent-sandbox#225).
• Scratch profiles: one SandboxTemplate and pool per runtime and profile (coder-<runtime>[-github]), so every Pod in a pool has the same rules. VPC CNI groups Pods by name, so mixing profiles in one pool could leak rules.
• Comma-separated runtimes and scratch_profiles: Coder checks presets with every template variable as a string, so list variables fail the preset check.
• Shared files: shared/start-agent.sh (policy check, agent as PID 1) and shared/defaults.json (GitHub ranges, DNS, resources) are read by both the template and cluster/.
• Policy check: in VPC CNI's default mode, a new Pod is open until its policy applies (up to about 30 s), and the rules can drop while it runs. The check waits until the API server is unreachable, and stops the agent if it becomes reachable. network_policy_gate = false turns it off where a profile can reach the API server.
• Agent as PID 1: under Kata, the web terminal got no input unless the agent was PID 1.
• coder_host_ip: Fully isolated has no DNS, so a host name access URL needs an /etc/hosts entry. A precondition fails the build if it is missing.
• AI Gateway token: the workspace does not get the owner's session token, which has coder:all. The start build uses it once to create a token with only user:read_personal (through hashicorp/http, deferred to apply with timestamp()), and the workspace gets that. The AI Gateway checks that a key is valid, not its scopes, so this works today. Coder deletes the session token before stop, so the scoped token cannot be revoked on stop and expires at the default token lifetime. Prebuilds create none; the claim build does.
• Dockerfile: no comment before FROM, because prettier-plugin-sh corrupts Dockerfiles with a leading comment block.

Related Issues

None

---

🤖 This PR was generated by Coder Agents on behalf of @bpmct.

[DevelopmentCats]

Aside from my NIT this LGTM