From e6f0a1b2f60c08687c30d23e8c521d40323d169c Mon Sep 17 00:00:00 2001
From: Yevhenii Shcherbina <evgeniy.shcherbina.es@gmail.com>
Date: Fri, 20 Feb 2026 15:41:54 -0500
Subject: [PATCH] docs: improve boundary docs (#22183)

---
 docs/ai-coder/agent-boundaries/nsjail/ecs.md  | 38 +++++++++++++++++++
 .../ai-coder/agent-boundaries/nsjail/index.md |  9 +++--
 docs/ai-coder/agent-boundaries/nsjail/k8s.md  | 16 ++++++++
 docs/manifest.json                            |  5 +++
 4 files changed, 64 insertions(+), 4 deletions(-)
 create mode 100644 docs/ai-coder/agent-boundaries/nsjail/ecs.md

diff --git a/docs/ai-coder/agent-boundaries/nsjail/ecs.md b/docs/ai-coder/agent-boundaries/nsjail/ecs.md
new file mode 100644
index 0000000000..77a45f02e9
--- /dev/null
+++ b/docs/ai-coder/agent-boundaries/nsjail/ecs.md
@@ -0,0 +1,38 @@
+# nsjail on ECS
+
+This page describes the runtime and permission requirements for running
+Boundary with the **nsjail** jail type on **Amazon ECS**.
+
+## Runtime & Permission Requirements for Running Boundary in ECS
+
+The setup for ECS is similar to [nsjail on Kubernetes](./k8s.md); that environment
+is better explored and tested, so the Kubernetes page is a useful reference. On
+ECS, requirements depend on the node OS and how ECS runs your tasks. The
+following examples use **ECS with Self Managed Node Groups** (EC2 launch type).
+
+---
+
+### Example 1: ECS + Self Managed Node Groups + Amazon Linux
+
+On **Amazon Linux** nodes with ECS, the default Docker seccomp profile enforced
+by ECS blocks the syscalls needed for Boundary. Because it is difficult to
+disable or modify the seccomp profile on ECS, you must grant `SYS_ADMIN` (along
+with `NET_ADMIN`) so that Boundary can create namespaces and run nsjail.
+
+**Task definition (Terraform) — `linuxParameters`:**
+
+```hcl
+container_definitions = jsonencode([{
+  name      = "coder-agent"
+  image     = "your-coder-agent-image"
+
+  linuxParameters = {
+    capabilities = {
+      add = ["NET_ADMIN", "SYS_ADMIN"]
+    }
+  }
+}])
+```
+
+This gives the container the capabilities required for nsjail when ECS uses the
+default Docker seccomp profile.
diff --git a/docs/ai-coder/agent-boundaries/nsjail/index.md b/docs/ai-coder/agent-boundaries/nsjail/index.md
index 5b1f7b6449..59a24b9d1c 100644
--- a/docs/ai-coder/agent-boundaries/nsjail/index.md
+++ b/docs/ai-coder/agent-boundaries/nsjail/index.md
@@ -4,11 +4,12 @@ nsjail is Agent Boundaries' default jail type that uses Linux namespaces to
 provide process isolation. It creates unprivileged network namespaces to control
 and monitor network access for processes running under Boundary.
 
-**Running on Docker?** See [nsjail on Docker](./docker.md) for runtime
-and permission requirements.
+**Running on Docker, Kubernetes, or ECS?** See the relevant page for runtime
+and permission requirements:
 
-**Running on Kubernetes?** See [nsjail on Kubernetes](./k8s.md) for runtime
-and permission requirements.
+- [nsjail on Docker](./docker.md)
+- [nsjail on Kubernetes](./k8s.md)
+- [nsjail on ECS](./ecs.md)
 
 ## Overview
 
diff --git a/docs/ai-coder/agent-boundaries/nsjail/k8s.md b/docs/ai-coder/agent-boundaries/nsjail/k8s.md
index b1ff6ba655..29ba3ae36b 100644
--- a/docs/ai-coder/agent-boundaries/nsjail/k8s.md
+++ b/docs/ai-coder/agent-boundaries/nsjail/k8s.md
@@ -111,3 +111,19 @@ EOT
 ```
 
 This ensures Boundary can create user namespaces with nsjail.
+
+### Running without user namespaces
+
+If the environment is restricted and you cannot enable user namespaces (e.g.
+Bottlerocket in EKS auto-mode), you can run Boundary with the
+`--no-user-namespace` flag. Use this when you have no way to allow user namespace creation.
+
+---
+
+### Example 3: EKS + Fargate (Firecracker VMs)
+
+nsjail is not currently supported on **EKS Fargate** (Firecracker-based VMs), which
+blocks the capabilities needed for nsjail.
+
+If you run on Fargate, we recommend using [landjail](../landjail.md) instead,
+provided kernel version supports it (Linux 6.7+).
diff --git a/docs/manifest.json b/docs/manifest.json
index fcf4fd8778..21f0b5bdc2 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -1024,6 +1024,11 @@
 											"title": "NS Jail on Kubernetes",
 											"description": "Runtime and permission requirements for running NS Jail on Kubernetes",
 											"path": "./ai-coder/agent-boundaries/nsjail/k8s.md"
+										},
+										{
+											"title": "NS Jail on ECS",
+											"description": "Runtime and permission requirements for running NS Jail on ECS",
+											"path": "./ai-coder/agent-boundaries/nsjail/ecs.md"
 										}
 									]
 								},