Skip to content

claude-code module: Document CAP_NET_ADMIN + sysbox-runc requirements for boundary, add backlink to docs #793

@matifali

Description

@matifali

Problem

When enable_boundary = true, the module silently requires:

  • CAP_NET_ADMIN capability on the workspace container
  • sysbox-runc (or equivalent) container runtime

Neither requirement is mentioned in the module README or the included Terraform example. A first-time user will enable boundary, provision a workspace, and hit a cryptic runtime error — with no hint of what's missing or where to look.

Note: These requirements apply to Docker-based templates. Requirements may differ for other runtimes (e.g. Kubernetes, VMs) — see the Coder boundary docs for runtime-specific setup.

Compounding this: the full boundary setup docs live in the coder/coder repo (published at coder.com/docs), but there is no backlink from the module README to those docs. Users are left to find them via web search.

Proposed Fix

  1. Add a prerequisites section to the README under the boundary section, e.g.:

    ## Prerequisites for `enable_boundary`
    
    Boundary uses Linux network namespaces. Requirements vary by runtime:
    
    - **Docker templates**: requires `CAP_NET_ADMIN` and a runtime that supports it (e.g. `sysbox-runc`)
    - **Other runtimes**: see the [Coder boundary docs](https://coder.com/docs/ai-coder/agent-boundaries/nsjail) for specifics
    
  2. Update the included Terraform example to show the required capability/runtime config alongside enable_boundary = true for the Docker case, so users have a working starting point.

  3. Add a backlink from the module README to the Coder boundary docs for full context.

Impact

Without this, every first-time user of enable_boundary will waste time debugging a non-obvious infrastructure requirement that has nothing to do with their Terraform code.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions