> [!NOTE] > Generated by Coder Agents. The branch and this description were written by an AI agent and need human review. ## Summary First of three stacked PRs for the docs IA overhaul (Proposal 1, section 3). This PR dissolves `docs/ai-coder/` into four top-level sidebar sections, in this order, where "Run AI coding agents in Coder" used to be: **Coder Agents**, **AI Governance** (with Agent Firewall and AI Gateway nested under it), **Agent Relay**, and **MCP server**. - Files move with `git mv`, so `git log --follow` keeps their history. The move includes every file in the moved folders, including pages that are not in the sidebar, such as `agent-firewall/example-policy.md`, and pages added to `main` after the first version of this PR, such as `agents/projects.md` (#30684) and `agents/acp-subagents.md` (#31430). - `docs/ai-coder/index.md`, `best-practices.md`, and `ide-agents.md` are deleted. Each has a redirect (see below). - `docs/manifest/` mirrors the new folders: `coder-agents.yml` (+ `coder-agents/`), `ai-governance.yml` (+ `ai-governance/`), `agent-relay.yml`, and `mcp-server.yml`. `ai-coder.yml` is deleted. The Projects and ACP subagents entries from `main` move with Coder Agents. - Every relative link and image path is fixed, both in the moved pages (their base directory changed) and in pages that link to them. This was done in one scripted pass from a clean `main` checkout. Every link was then checked to resolve on disk. - Commit 2, `chore: point in-product docs links at the new docs paths`, updates docs URLs outside `docs/`: `site/` `docs()` links, Go error strings and comments, `README.md`, `server.json`, templatebuilder modules, and the doc-check skill. Commit 4 reverts the unversioned `https://coder.com/docs/...` URLs among them (see below), so after this PR only these differ from `main` outside `docs/`: the `site/` `docs()` links, the versioned `cli/cliui` troubleshooting links, and repo file paths in comments and the doc-check skill's examples (`docs/coder-agents/...`, `docs/templates/...`). You can drop commit 2; the redirects cover the old URLs. - **#31646 (Templates) was squash-merged into this branch** as `98377a3a3b`. This PR now also carries the Templates move (`docs/admin/templates/**` → `docs/templates/**`, plus `template-from-scratch.md` and `testing-templates.md`) and its chore changes. Refer to #31646 for that part's move map, redirects, and review. - Commit 4, `fix: keep docs links healthy before the release`, keeps links working on the live site until a release that includes this stack becomes the default docs version: - Hand-written pages that linked to moved pages with absolute `https://coder.com/docs/...` URLs now use relative links, anchors kept. The new paths 404 on the live site today, but relative links resolve for every version and are checked locally. - Hardcoded, unversioned `https://coder.com/docs/<new path>` URLs outside `docs/` that the chore commits introduced (Go strings including the prebuilds metric help, CLI help, the `agentFallbackTroubleshootingURL` default, `README.md`, `server.json`, examples, templatebuilder files, and one `site/` constant) go back to their current paths. Then `make gen` regenerated the generated table in `docs/admin/integrations/prometheus.md`, `scripts/metricsdocgen/generated_metrics`, the CLI golden files, and `docs/reference/cli/templates/{create,edit}.md`. See "Post-release follow-up". - The `site/` `docs()` changes and the `cli/cliui` links stay, because those URLs are versioned (`/docs/@vX.Y.Z/...`) and resolve once the release ships. - Commit 5, `docs: prefix relative links in the moved pages with ./`, adds `./` to 13 relative links that the move script wrote without it, in `docs/mcp-server.md` and three Templates pages. They resolved, but every other relative link in the docs starts with `./` or `../`. - Commit 6, `docs: keep the coding agent module guidance in the templates docs`, adds an **AI agent modules** section to `docs/templates/extending-templates/modules.md`. Deleting `docs/ai-coder/index.md` removed the only instructions for adding a terminal coding agent to a template with a registry module. The example (`registry.coder.com/coder/claude-code/coder`, `version = "~> 5.2"`) passes `terraform validate`, and the Template Builder labels it cites match `site/src/pages/TemplateBuilder/ModuleSelectStep.tsx`. Stack: **this PR** (with #31646 squash-merged in) → `docs/ia-tutorials-nav` (#31647, Tutorials + nav renames) → `docs/ia-workspaces-folder` (#31650, folder rename). Refs: Linear DOCS-1154, DOCS-1179, and DOCS-1479 for the coder.com and router redirect fix. ## Move map | Old | New | | --- | --- | | `docs/ai-coder/agents/**` (25 files) | `docs/coder-agents/**` | | `docs/ai-coder/ai-governance.md` | `docs/ai-governance/index.md` | | `docs/ai-coder/agent-firewall/**` (9 files) | `docs/ai-governance/agent-firewall/**` | | `docs/ai-coder/ai-gateway/**` (26 files) | `docs/ai-governance/ai-gateway/**` | | `docs/ai-coder/agent-relay/**` (3 files) | `docs/agent-relay/**` | | `docs/ai-coder/mcp-server.md` | `docs/mcp-server.md` | | `docs/ai-coder/index.md` | deleted | | `docs/ai-coder/best-practices.md` | deleted | | `docs/ai-coder/ide-agents.md` | deleted | ## Redirects added Appended to `docs/redirects.json`, using the absolute `/docs/...` format that `main` validates today. Wildcards cover every page under each moved folder, including pages that are not in the sidebar and the pages added to `main` since the first version of this PR. | Source | Destination | | --- | --- | | `/docs/ai-coder` | `/docs/coder-agents` (deleted hub, **please confirm**) | | `/docs/ai-coder/best-practices` | `/docs/coder-agents` (deleted, **please confirm**) | | `/docs/ai-coder/ide-agents` | `/docs/user-guides/workspace-access` (deleted, **please confirm**) | | `/docs/ai-coder/ai-governance` | `/docs/ai-governance` | | `/docs/ai-coder/mcp-server` | `/docs/mcp-server` | | `/docs/ai-coder/agents/:path*` | `/docs/coder-agents/:path*` | | `/docs/ai-coder/agent-firewall/:path*` | `/docs/ai-governance/agent-firewall/:path*` | | `/docs/ai-coder/ai-gateway/:path*` | `/docs/ai-governance/ai-gateway/:path*` | | `/docs/ai-coder/agent-relay/:path*` | `/docs/agent-relay/:path*` | None of the 3 existing rules in `docs/redirects.json` points into `ai-coder/`, so no destinations needed updating. **coder.com and router static redirects.** coder.com applies its own `redirects.json` and the rules it generates from this file before it hands `/docs` to the docs-engine router, which applies its own static `redirects.json` before the page. Three older static rules in both repos send `/docs/templates`, `/docs/templates/open-in-coder`, and `/docs/templates/troubleshooting` to `/docs/admin/templates/...`, and the `/docs/admin/templates/:path*` rule here sends them back, so each loops once a release with this layout is the docs mainline. A static `/docs/workspaces` rule would also hide the new `docs/workspaces/index.md` page from #31650. coder/coder.com#1201 and coder/docs-engine#304 (draft, DOCS-1479) remove those rules; they must merge when that release becomes the mainline, not before, because the old-layout mainline still needs them. A chain simulation of every page and static source on each branch of this stack finds no other loops or hidden pages. The `/docs/ai-coder/...` and other legacy rules there still work; some now take two redirects. ## Deviations from the proposal - **Glossary "IDE agent" entry.** The proposal says to remove this link and leave plain text. I pointed it at Access your workspace (`docs/user-guides/workspace-access/index.md`) instead, the same page the `ide-agents` redirect uses, because "Refer to IDE agents." with no link reads as a dead end. The "Coding agent" entry now links to Coder Agents, as the proposal says. - **Top-level icons.** The new sections need icons. I chose `wand.svg` (Coder Agents, the old ai-coder icon), `ai_intelligence.svg` (AI Governance), `link.svg` (Agent Relay), and `plug.svg` (MCP server). - **Coding agent module guidance.** Kept on the Reuse template code page (commit 6) instead of deleted with `docs/ai-coder/index.md`. The best-practices and IDE-agent pages are deleted as proposed. - **Order relative to Administration.** In this PR the four sections sit where `ai-coder` was, after Administration. PR C moves Administration after MCP server to reach the final order. - **`docs/mcp-server.md` repo link.** A relative link to `codersdk/toolsdk/toolsdk.go`, outside `docs/`, was re-based for the new depth. - **Left unchanged on purpose:** - Database migrations and the notification `.golden` files rendered from them still contain `coder.com/docs/ai-coder/...` URLs. Existing migrations can't be edited, so those links rely on the redirects. - `aibridge/client/client.go` links to a commit-pinned GitHub permalink, which still resolves. - Test fixtures in `scripts/docsredirectscheck` and `.github/workflows/test-docs-preview-mapper.sh` use `ai-coder` as sample data. - `site/src/pages/AgentsPage/components/ChatElements/tools/Tool.stories.tsx` uses `https://coder.com/docs/ai-coder/ai-gateway` as a sample web search result. Changing it would only change a visual snapshot. ## Open questions for Nick 1. Do you agree with the three redirect targets for the deleted pages above? 2. Should the "IDE agent" glossary entry link to Access your workspace (current) or be plain text (proposal)? 3. Are the icons for the new top-level sections OK? 4. Open PRs that touch the moved files, checked with `git merge-tree` against this branch. I didn't change them. - #31169 merges cleanly: Git's rename detection carries its edit to `docs/ai-governance/ai-gateway/clients/claude-code.md`, and its new relative link still resolves at the new path. - #30262 now targets `tk/ai-gateway-responses-ws-endpoint` and conflicts with `main` in 21 files. Against this branch it conflicts in the same 21 files, with `codex.md` at its new path, so this PR doesn't add new conflicts. Its new relative links still resolve after the move. - #30805 conflicts in `docs/redirects.json`. It already conflicts with `main` there, because `main` added the `/docs/about/screenshots` and `/docs/install/cli` rules. ## Release No backport to `release/2.39` for now; Nick may apply it by hand later. A cherry-pick of this branch onto `release/2.39` conflicts in 25 files, and #31647 and #31650 would need the same treatment to keep the stack together. coder/coder.com#1201 and coder/docs-engine#304 merge when the first release line that carries this layout becomes the docs mainline (2.38 today). ## Known limitations - **CLI newer than its server.** The `cli/cliui` troubleshooting links append `/templates/troubleshooting#...` to the server's versioned docs URL. A CLI from this release against an older server prints `/docs/@v2.38.x/templates/troubleshooting#...`. The router's static `/docs/templates/:page(open-in-coder|troubleshooting)` rule redirects that to the old page today, but coder/docs-engine#304 removes that rule to fix the loop, so after the cutover that case gets the version's not-found page. ## Post-release follow-up After a release that includes this stack becomes the default docs version on coder.com, point these hardcoded URLs at the new paths. They work today and redirect after the release, so nothing breaks in the meantime. Anchors are unchanged. Rerun `make gen` afterward to update `docs/admin/integrations/prometheus.md`, `scripts/metricsdocgen/generated_metrics`, the CLI golden files, and `docs/reference/cli/templates/{create,edit}.md`. | Current (old) URL | Post-release URL | Files | | --- | --- | --- | | `https://coder.com/docs/ai-coder/agents` | `https://coder.com/docs/coder-agents` | `.claude/skills/doc-check/output.md`, `README.md` | | `https://coder.com/docs/ai-coder/agents/architecture` | `https://coder.com/docs/coder-agents/architecture` | `coderd/x/chatd/chattool/execute_test.go`, `codersdk/toolsdk/workspacetools/execute.go` | | `https://coder.com/docs/ai-coder/ai-gateway` | `https://coder.com/docs/ai-governance/ai-gateway` | `README.md`, `coderd/templatebuilder/modules/claude-code/module.json`, `coderd/templatebuilder/modules/codex/module.json` | | `https://coder.com/docs/ai-coder/mcp-server` | `https://coder.com/docs/mcp-server` | `server.json` | | `https://coder.com/docs/admin/templates` | `https://coder.com/docs/templates` | `README.md` | | `https://coder.com/docs/admin/templates/extending-templates/docker-in-workspaces` | `https://coder.com/docs/templates/extending-templates/docker-in-workspaces` | `examples/templates/docker-devcontainer/main.tf` | | `https://coder.com/docs/admin/templates/extending-templates/parameters` | `https://coder.com/docs/templates/extending-templates/parameters` | `examples/parameters-dynamic-options/README.md`, `examples/parameters/README.md`, `examples/parameters/main.tf`, `examples/templates/kubernetes-envbox/README.md`, `examples/workspace-tags/README.md` | | `https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces` | `https://coder.com/docs/templates/extending-templates/prebuilt-workspaces` | `coderd/prebuilds/api.go`, `enterprise/coderd/prebuilds/metricscollector.go` (metric help text) | | `https://coder.com/docs/admin/templates/extending-templates/workspace-tags` | `https://coder.com/docs/templates/extending-templates/workspace-tags` | `examples/workspace-tags/README.md` | | `https://coder.com/docs/admin/templates/managing-templates` | `https://coder.com/docs/templates/managing-templates` | `cli/templatecreate.go`, `cli/templateedit.go` (CLI help) | | `https://coder.com/docs/admin/templates/managing-templates/image-management` | `https://coder.com/docs/templates/managing-templates/image-management` | `coderd/templatebuilder/bases/docker/README.md`, `coderd/templatebuilder/bases/kubernetes/README.md` | | `https://coder.com/docs/admin/templates/troubleshooting` | `https://coder.com/docs/templates/troubleshooting` | `agent/agentscripts/agentscripts.go`, `coderd/render/escape_internal_test.go`, `codersdk/deployment.go` (`agentFallbackTroubleshootingURL` default) | | `https://coder.com/docs/tutorials/template-from-scratch` | `https://coder.com/docs/templates/template-from-scratch` | `site/src/pages/TemplateBuilder/TemplateAlternatives.tsx` | ## Validation run - `make gen/docs-manifest`: clean diff afterward. - `make lint/docs-manifest`, `lint/docs-redirects` (`go run ./scripts/docsredirectscheck -base origin/main`: 15 rules OK, no removed-route warning), `lint/docs-html`, `lint/emdash`: pass. - `pnpm check-docs` (markdownlint + table formatter): pass. - Vale (`vale --no-exit docs/`): the same 12 warnings and 1 error as `main`, all pre-existing. Suggestions drop from 646 to 645; the one removed was in the deleted `ide-agents.md`. - Local relative-link check over `docs/**/*.md`: 0 unresolved links or images (also 0 on `main`). - Pre-commit hook: `make pre-commit-light` on the docs commit, and the full `make pre-commit` (gen, fmt, lint/go, lint/ts, build, and others) on the chore commit. Both passed. - Targeted tests: - Go: `go test ./coderd/x/chatd/chattool/... ./codersdk/toolsdk/... ./coderd/templatebuilder/...`. - Site: Vitest for the touched directories (107 files, 1879 tests), and the story tests for `CoderAgentsProductCard`, `GroupSettingsPageView`, `GatewayKeysPageView`, and `ModelForm` (4 files, 63 tests). - Every `docs()` path and anchor in the `site/` and Go diff resolves to a page and heading in this branch. - Frontend deep review (all 8 roles) on the `site/` diff of PRs A and B: no blocking or should-fix findings. Nits on existing code that this PR only touched, not changed here: a single-use `docsLink` constant in `ChatAccessDeniedAlert.tsx`, and assertion-only `play` functions in the `GatewayKeysPageView`, `ModelForm`, `CoderAgentsProductCard`, and `GroupSettingsPageView` stories. - Page counts: `docs/**/*.md` (excluding `.style`) 490 → 487; `manifest.json` routes 495 → 492. With #31646 squash-merged in, the counts don't change, because the Templates move only moves files. - **Link health (commit 4):** - linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`, like the weekly docs job (`umbrelladocs/action-linkspector`, `reporter: local`, `filter_mode: nofilter`). I ran it locally with Chrome in `--no-sandbox` mode. - `origin/main`: 0 errors. Before the fix (`17e54ad555`): 6 errors, all `https://coder.com/docs/<new path>` 404s (`shared-workspaces.md:19`, `esr-2.24-2.29-upgrade.md:80-82`, `tasks-to-chats-migration.md:73`, `prometheus.md:298`). After the fix (`def074caab`): 0 errors. A first run after the fix also flagged a Red Hat URL in `install/server/openshift.md`. That URL is unchanged from `main`, and it passed on a rerun, so the failure was transient. - After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (15 rules OK against `origin/main`), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the relative-link check (0 unresolved in 3416 links) pass. The full `make pre-commit`, including `make gen`, passed on the commit. - Tests after the fix: - Go: `go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig'`, `./enterprise/cli -run TestEnterpriseCommandHelp`, `./coderd/render`, `./agent/agentscripts`, `./coderd/prebuilds`, `./enterprise/coderd/prebuilds`, `./coderd/x/chatd/chattool/...`, `./codersdk/toolsdk/...`, `./coderd/templatebuilder/...`. - Site: Vitest for `src/pages/TemplateBuilder` (7 files, 67 tests). - **After the rebase onto `ccf5ec74ae`** (commits 5 and 6 included): `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (15 rules OK), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and a relative-link and anchor check over the changed pages pass. The only unresolved anchor, `docs/ai-governance/ai-gateway/cost-controls.md` → `enterprise.md#list-organization-ai-spend-by-user`, is also broken on `main`. The pre-commit hook (`make pre-commit-light`, because both new commits touch only `docs/`) passed on commits 5 and 6. The rebased code commits rely on CI for Go and TypeScript checks. - **Redirect chains:** a Node simulation of coder.com's static rules, its generated rules from this branch's `docs/redirects.json`, the router's static rules, the page, then this branch's rules on a miss, over every page and exact static source, reports the 3 loops above and nothing else new; with coder/coder.com#1201 and coder/docs-engine#304 applied, 0. - **Skipped:** the docs-engine sync check, which was not available in this environment. <details> <summary>Implementation notes</summary> - Rebuilt on `main` at `ccf5ec74ae` (2026-11-03) to clear conflicts with `main`, after an earlier rebase the same day onto `1a963c628d`. The previous rebuild was on `9839406ff7` (2026-11-02), and the first version on `9b8d880d63` (2026-10-23). - Rebase conflicts with #31603, which added `target="_blank" rel="noreferrer"` to docs links: 4 `site/` files in the chore commit and 5 in the Templates commit. Each kept `main`'s version of the link with only the docs path changed. Vitest for the 7 affected page directories (233 tests) and the story tests for the 8 changed or affected stories (102 tests) pass, and every `docs()` path in `site/src` resolves except the same 13 that are unresolved on `main`. - Rebase conflict: `docs/manifest/coder-agents.yml`. `main` added `docs/ai-coder/agents/bring-your-own-mcp-servers.md`; it moves to `docs/coder-agents/` with its sidebar entry, and its `../../user-guides/` links become `../user-guides/`. - Folded into the Templates commit: a link that `main` added to `docs/user-guides/workspace-dotfiles.md` (#31606) now points at `../templates/extending-templates/environment-variables.md`. - `git range-diff` against `def074caab`, the head before both rebases, shows only those changes. - The move script reads every page from the clean `main` checkout and resolves each relative link (inline, reference-style, and HTML `src`/`href`) against the page's **old** directory. It maps the target through the move map and recomputes the link from the page's **new** directory. It runs once and refuses to run on a dirty `docs/` tree, so it can't apply the path math twice. It also rewrites absolute `coder.com/docs/...` and `github.com/coder/coder/(blob|edit|tree)/main/docs/...` URLs, and skips fenced code blocks and inline code. - Before reusing the script, I ran it on the old base and diffed the result against the old commit. The only differences were the two hand-edited glossary entries and table padding from the formatter, so the rebuild applies the same changes to the current `main`. - Afterward, `grep -r ai-coder docs/` finds matches only in `docs/redirects.json`. - Changes from the earlier version of this branch: 2 more pages move (`agents/projects.md`, `agents/acp-subagents.md`) and their sidebar entries move with them. The chore commit also updates `SessionSummaryTable.tsx` (new on `main`) and the doc-check skill's `output.md` (its examples moved there from `SKILL.md`). The `AICostControl.tsx` anchor question is gone, because `main` fixed it. </details> --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
13 KiB
title
| title |
|---|
| Network isolation |
Use your template to run the AI agent in a separate sandbox from the user's development environment. You control which files and networks the agent can access without restricting the user's access.
This guide uses Kubernetes, but you can use another sandbox, such as Bubblewrap with firewall rules. Coder selects the workspace agent that runs chat tools. You configure the sandbox around that agent.
Note
Sandboxing in Coder is at an early stage and is subject to change. Contact us to share feedback.
How it works
- The user's Pod keeps its normal development access.
- The AI agent's Pod runs as a non-root user with a network policy that allows Coder.
- Both Pods share project files, but have separate home directories.
Network policies select Pods, not individual containers.
Use separate Pods to give the user and AI agent different network access.
The Pods run on the same node and share one ReadWriteOnce persistent volume claim (PVC).
They do not need ReadWriteMany storage.
1. Configure the template
Use a test namespace and a workspace without sensitive data. You need:
- A Linux cluster with NetworkPolicy enforcement turned on for standalone Pods.
- A default storage class that provides a volume writable by user and group ID
1000. - A fixed IPv4 address and Transmission Control Protocol (TCP) port for Coder, including agent downloads and relay connections.
- A Coder provisioner with permission to create Pods, a PVC, a ConfigMap, and a NetworkPolicy in that namespace.
Check these permissions using the provisioner's Kubernetes credentials:
kubectl auth can-i create pods -n YOUR_NAMESPACE
kubectl auth can-i create persistentvolumeclaims -n YOUR_NAMESPACE
kubectl auth can-i create configmaps -n YOUR_NAMESPACE
kubectl auth can-i create networkpolicies.networking.k8s.io -n YOUR_NAMESPACE
Each command must return yes.
The provisioner also needs permission to read, update, and delete these resources.
Warning
Do not run untrusted code until the network tests pass. Kubernetes can accept a NetworkPolicy without enforcing it, leaving the agent's network access unrestricted.
For Google Kubernetes Engine (GKE), check network policy enforcement. For Amazon Virtual Private Cloud (VPC) Container Network Interface (CNI), use Deployment-managed Pods instead of this example's standalone Pods. AWS documents unreliable enforcement for standalone Pods.
Save this Terraform as main.tf in an empty template directory.
Edit the locals block at the top of the file with your namespace and Coder server address.
main.tf: two Pods, one project volume, and an agent network policy
terraform {
required_providers {
coder = { source = "coder/coder" }
kubernetes = { source = "hashicorp/kubernetes" }
}
}
locals {
# Edit these values for your cluster and Coder deployment.
# Use ~/.kube/config on the provisioner host instead of in-cluster authentication.
use_kubeconfig = false
# Existing namespace for workspace resources.
namespace = "coder-sandbox-test"
# Storage class for the shared project PVC. Null uses the cluster default.
storage_class_name = null
# Hostname in the Coder access URL, without scheme or port.
coder_host = "coder.example.com"
# Trusted fixed IPv4 address of the external Coder endpoint, not a cluster Service or node IP.
coder_ip = "192.0.2.10"
# TCP port of the Coder endpoint (including agent downloads and embedded DERP).
coder_port = 443
}
provider "kubernetes" {
config_path = local.use_kubeconfig ? "~/.kube/config" : null
}
data "coder_workspace" "me" {}
data "coder_provisioner" "me" {}
resource "coder_agent" "dev" {
os = "linux"
arch = data.coder_provisioner.me.arch
dir = "/home/coder/project"
}
resource "coder_agent" "dev-coderd-chat" {
os = "linux"
arch = data.coder_provisioner.me.arch
dir = "/home/coder/project"
env = { CODER_AGENT_EXP_MCP_CONFIG_FILES = "/etc/coder/mcp.json" }
}
locals {
name = "coder-${data.coder_workspace.me.id}"
labels = { "com.coder.workspace.id" = data.coder_workspace.me.id }
}
resource "kubernetes_persistent_volume_claim_v1" "project" {
metadata {
name = "${local.name}-project"
namespace = local.namespace
}
wait_until_bound = false
spec {
access_modes = ["ReadWriteOnce"]
storage_class_name = local.storage_class_name
resources {
requests = { storage = "10Gi" }
}
}
}
resource "kubernetes_config_map_v1" "mcp" {
metadata {
name = "${local.name}-mcp"
namespace = local.namespace
}
data = { "mcp.json" = jsonencode({ mcpServers = {} }) }
}
resource "kubernetes_network_policy_v1" "sandbox" {
metadata {
name = "${local.name}-sandbox"
namespace = local.namespace
}
spec {
pod_selector {
match_labels = merge(local.labels, { "coder.com/agent-role" = "sandbox" })
}
policy_types = ["Egress"]
egress {
to {
ip_block {
cidr = "${local.coder_ip}/32"
}
}
ports {
protocol = "TCP"
port = local.coder_port
}
}
}
}
resource "kubernetes_pod_v1" "dev" {
count = data.coder_workspace.me.start_count
metadata {
name = "${local.name}-dev"
namespace = local.namespace
labels = merge(local.labels, { "coder.com/agent-role" = "dev" })
}
spec {
automount_service_account_token = false
host_network = false
security_context {
run_as_user = 1000
run_as_group = 1000
fs_group = 1000
run_as_non_root = true
seccomp_profile { type = "RuntimeDefault" }
}
host_aliases {
ip = local.coder_ip
hostnames = [local.coder_host]
}
container {
name = "dev"
image = "codercom/example-base:ubuntu"
command = ["sh", "-c", coder_agent.dev.init_script]
working_dir = "/home/coder/project"
env {
name = "CODER_AGENT_TOKEN"
value = coder_agent.dev.token
}
volume_mount {
name = "home"
mount_path = "/home/coder"
}
volume_mount {
name = "project"
mount_path = "/home/coder/project"
}
volume_mount {
name = "tmp"
mount_path = "/tmp"
}
}
volume {
name = "project"
persistent_volume_claim {
claim_name = kubernetes_persistent_volume_claim_v1.project.metadata[0].name
}
}
volume {
name = "home"
empty_dir {}
}
volume {
name = "tmp"
empty_dir {}
}
}
}
resource "kubernetes_pod_v1" "sandbox" {
count = data.coder_workspace.me.start_count
depends_on = [kubernetes_network_policy_v1.sandbox]
metadata {
name = "${local.name}-dev-coderd-chat"
namespace = local.namespace
labels = merge(local.labels, { "coder.com/agent-role" = "sandbox" })
}
spec {
automount_service_account_token = false
host_network = false
security_context {
run_as_user = 1000
run_as_group = 1000
fs_group = 1000
run_as_non_root = true
seccomp_profile {
type = "RuntimeDefault"
}
}
# Dev schedules independently, including with WaitForFirstConsumer storage.
affinity {
pod_affinity {
required_during_scheduling_ignored_during_execution {
topology_key = "kubernetes.io/hostname"
label_selector {
match_labels = merge(local.labels, { "coder.com/agent-role" = "dev" })
}
}
}
}
host_aliases {
ip = local.coder_ip
hostnames = [local.coder_host]
}
container {
name = "dev-coderd-chat"
image = "codercom/example-base:ubuntu"
command = ["sh", "-c", coder_agent.dev-coderd-chat.init_script]
working_dir = "/home/coder/project"
env {
name = "CODER_AGENT_TOKEN"
value = coder_agent.dev-coderd-chat.token
}
env {
name = "CODER_AGENT_EXP_MCP_CONFIG_FILES"
value = "/etc/coder/mcp.json"
}
security_context {
allow_privilege_escalation = false
read_only_root_filesystem = true
run_as_non_root = true
capabilities { drop = ["ALL"] }
}
volume_mount {
name = "home"
mount_path = "/home/coder"
}
volume_mount {
name = "project"
mount_path = "/home/coder/project"
}
volume_mount {
name = "tmp"
mount_path = "/tmp"
}
volume_mount {
name = "mcp"
mount_path = "/etc/coder"
read_only = true
}
}
volume {
name = "project"
persistent_volume_claim {
claim_name = kubernetes_persistent_volume_claim_v1.project.metadata[0].name
}
}
volume {
name = "home"
empty_dir {}
}
volume {
name = "tmp"
empty_dir {}
}
volume {
name = "mcp"
config_map {
name = kubernetes_config_map_v1.mcp.metadata[0].name
}
}
}
}
Use the Coder hostname without https:// or a port.
Use an external IP address, not a cluster Service or node IP.
hostAliases lets the agent find Coder at this IP without DNS.
If your cluster has no default storage class, set storage_class_name to one that fits the requirements above.
If the provisioner runs outside the cluster, set use_kubeconfig = true.
Provide ~/.kube/config on the provisioner host.
Otherwise, the example uses in-cluster authentication.
The AI agent runs as user ID 1000, without Linux capabilities or a Kubernetes service-account token.
It can write to its home, temporary directories, and shared project, but not system files.
It uses the runtime's default security profile.
The network policy allows Coder's IP and TCP port, but not DNS.
Coder selects the agent whose name ends in -coderd-chat.
Use this ending on exactly one top-level agent.
2. Create a workspace
Sign in to Coder. From the template directory, run:
terraform init
terraform validate
coder templates push sandbox-k8s --directory .
coder create sandbox-test --template sandbox-k8s
After the template passes validation, wait for both agents to connect.
In Agents, start a chat attached to sandbox-test.
Ask the chat to run:
id -u
touch /home/coder/project/sandbox-check
touch /etc/sandbox-check
The first command must print 1000.
The agent must create the project file but fail to write to /etc.
Read each command's output, not only the chat summary.
3. Test network access
Try GitHub and the npm registry from the user's terminal:
curl --noproxy '*' --head --max-time 10 https://github.com
curl --noproxy '*' --head --max-time 10 https://registry.npmjs.org
Both requests must return HTTP headers. Then ask the chat to run the same commands. Both must fail with a DNS error, a connection error, or a timeout. The chat must still be able to run commands through Coder.
A DNS error does not prove that the policy blocks connections to IP addresses. Find GitHub's IP address from the user's Pod. Repeat the request from the user's terminal and the chat with that address:
# Run in the user's Pod.
getent ahostsv4 github.com
# Replace GITHUB_IP with an address from that output. Run in both Pods.
curl --noproxy '*' --head --max-time 10 --resolve github.com:443:GITHUB_IP https://github.com
The user's request must succeed, and the agent's request must fail to connect. If the agent reaches either site, stop the test workspace. Fix policy enforcement before continuing.
To test PostgreSQL, use a test database you control.
Run SELECT 1 from the user's terminal.
Ask the chat to run the same query.
The user's request must succeed.
The agent's request must fail to connect.
A login error does not count as a blocked connection.
If the user cannot reach GitHub or npm, fix that connection before testing the agent.
Limits
Other NetworkPolicies can allow connections that this policy blocks. Your network plugin can also allow traffic to the node or its local DNS service. Review these exceptions in the Kubernetes NetworkPolicy documentation.
The agent can read any credentials you give it, edit shared files, and send data to Coder. Keep workspace Model Context Protocol (MCP) configuration outside the shared project. This policy does not restrict organization MCP servers. Restrict their tools and credentials separately.
If you use another sandbox, apply it to the full workspace agent and its child processes. Restricting only a shell leaves file tools and workspace MCP processes outside the sandbox.