Files
coder/docs/coder-agents/platform-controls/agent-isolation.md
T
coder[bot]andNick Vigilante a7f3e3b685 docs: promote the AI sections and Templates to the top level of the sidebar (#31645)
> [!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>
2026-11-04 17:15:42 -05:00

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.