mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
docs: restructure agent boundaries from /boundary/ to /agent-boundaries/ (#21798)
## Summary This PR restructures the Agent Boundaries documentation to improve URL clarity and consistency: ### Changes - Renames `/docs/ai-coder/boundary/` to `/docs/ai-coder/agent-boundaries/` - Renames `agent-boundary.md` to `index.md` for cleaner URLs - Updates all internal doc references to the new paths - Updates `manifest.json` with new paths - Updates prose references from "Boundary" to "Agent Boundaries" throughout the documentation (33 changes across 4 files) ### New URL structure | Old URL | New URL | |---------|----------| | `/docs/ai-coder/boundary/agent-boundary` | `/docs/ai-coder/agent-boundaries` | | `/docs/ai-coder/boundary/nsjail` | `/docs/ai-coder/agent-boundaries/nsjail` | | `/docs/ai-coder/boundary/landjail` | `/docs/ai-coder/agent-boundaries/landjail` | | `/docs/ai-coder/boundary/rules-engine` | `/docs/ai-coder/agent-boundaries/rules-engine` | | `/docs/ai-coder/boundary/version` | `/docs/ai-coder/agent-boundaries/version` | ### Follow-up required Redirects need to be added to `coder/coder.com` for the old URLs: - `/docs/ai-coder/agent-boundary` → `/docs/ai-coder/agent-boundaries` (this one is currently 404'ing from Google search results) - `/docs/ai-coder/boundary/:path*` → `/docs/ai-coder/agent-boundaries/:path*` --- Created on behalf of @mattvollmer --------- Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com> Co-authored-by: Matt Vollmer <matthewjvollmer@outlook.com>
This commit is contained in:
blinkagent[bot]
+90
-48
@@ -1,32 +1,41 @@
|
||||
# Agent Boundary
|
||||
# Agent Boundaries
|
||||
|
||||
Agent Boundaries are process-level firewalls that restrict and audit what autonomous programs, such as AI agents, can access and use.
|
||||
Agent Boundaries are process-level firewalls that restrict and audit what
|
||||
autonomous programs, such as AI agents, can access and use.
|
||||
|
||||
Example of Agent Boundaries blocking a process.
|
||||
Example
|
||||
of Agent Boundaries blocking a process.
|
||||
|
||||
## Supported Agents
|
||||
|
||||
Agent Boundaries support the securing of any terminal-based agent, including your own custom agents.
|
||||
Agent Boundaries support the securing of any terminal-based agent, including
|
||||
your own custom agents.
|
||||
|
||||
## Features
|
||||
|
||||
Agent Boundaries offer network policy enforcement, which blocks domains and HTTP verbs to prevent exfiltration, and writes logs to the workspace.
|
||||
Agent Boundaries offer network policy enforcement, which blocks domains and HTTP
|
||||
verbs to prevent exfiltration, and writes logs to the workspace.
|
||||
|
||||
Agent Boundaries also stream audit logs to Coder's control plane for centralized
|
||||
monitoring of HTTP requests.
|
||||
|
||||
## Getting Started with Boundary
|
||||
## Getting Started with Agent Boundaries
|
||||
|
||||
The easiest way to use Agent Boundaries is through existing Coder modules, such as the [Claude Code module](https://registry.coder.com/modules/coder/claude-code). It can also be ran directly in the terminal by installing the [CLI](https://github.com/coder/boundary).
|
||||
The easiest way to use Agent Boundaries is through existing Coder modules, such
|
||||
as the
|
||||
[Claude Code module](https://registry.coder.com/modules/coder/claude-code). It
|
||||
can also be ran directly in the terminal by installing the
|
||||
[CLI](https://github.com/coder/boundary).
|
||||
|
||||
## Configuration
|
||||
|
||||
> [!NOTE]
|
||||
> For information about version requirements and compatibility, see the [Version Requirements](./version.md) documentation.
|
||||
|
||||
Boundary is configured using a `config.yaml` file. This allows you to maintain allow lists and share detailed policies with teammates.
|
||||
Agent Boundaries is configured using a `config.yaml` file. This allows you to
|
||||
maintain allow lists and share detailed policies with teammates.
|
||||
|
||||
In your Terraform module, enable Boundary with minimal configuration:
|
||||
In your Terraform module, enable Agent Boundaries with minimal configuration:
|
||||
|
||||
```tf
|
||||
module "claude-code" {
|
||||
@@ -36,23 +45,29 @@ module "claude-code" {
|
||||
}
|
||||
```
|
||||
|
||||
Create a `config.yaml` file in your template directory with your policy. For the Claude Code module, use the following minimal configuration:
|
||||
Create a `config.yaml` file in your template directory with your policy. For the
|
||||
Claude Code module, use the following minimal configuration:
|
||||
|
||||
```yaml
|
||||
allowlist:
|
||||
- "domain=dev.coder.com" # Required - use your Coder deployment domain
|
||||
- "domain=api.anthropic.com" # Required - API endpoint for Claude
|
||||
- "domain=statsig.anthropic.com" # Required - Feature flags and analytics
|
||||
- "domain=claude.ai" # Recommended - WebFetch/WebSearch features
|
||||
- "domain=*.sentry.io" # Recommended - Error tracking (helps Anthropic fix bugs)
|
||||
- "domain=dev.coder.com" # Required - use your Coder deployment domain
|
||||
- "domain=api.anthropic.com" # Required - API endpoint for Claude
|
||||
- "domain=statsig.anthropic.com" # Required - Feature flags and analytics
|
||||
- "domain=claude.ai" # Recommended - WebFetch/WebSearch features
|
||||
- "domain=*.sentry.io" # Recommended - Error tracking (helps Anthropic fix bugs)
|
||||
log_dir: /tmp/boundary_logs
|
||||
proxy_port: 8087
|
||||
log_level: warn
|
||||
```
|
||||
|
||||
For a basic recommendation of what to allow for agents, see the [Anthropic documentation on default allowed domains](https://code.claude.com/docs/en/claude-code-on-the-web#default-allowed-domains). For a comprehensive example of a production Boundary configuration, see the [Coder dogfood policy example](https://github.com/coder/coder/blob/main/dogfood/coder/boundary-config.yaml).
|
||||
For a basic recommendation of what to allow for agents, see the
|
||||
[Anthropic documentation on default allowed domains](https://code.claude.com/docs/en/claude-code-on-the-web#default-allowed-domains).
|
||||
For a comprehensive example of a production Agent Boundaries configuration, see
|
||||
the
|
||||
[Coder dogfood policy example](https://github.com/coder/coder/blob/main/dogfood/coder/boundary-config.yaml).
|
||||
|
||||
Add a `coder_script` resource to mount the configuration file into the workspace filesystem:
|
||||
Add a `coder_script` resource to mount the configuration file into the workspace
|
||||
filesystem:
|
||||
|
||||
```tf
|
||||
resource "coder_script" "boundary_config_setup" {
|
||||
@@ -69,40 +84,65 @@ resource "coder_script" "boundary_config_setup" {
|
||||
}
|
||||
```
|
||||
|
||||
Boundary automatically reads `config.yaml` from `~/.config/coder_boundary/` when it starts, so everyone who launches Boundary manually inside the workspace picks up the same configuration without extra flags. This is especially convenient for managing extensive allow lists in version control.
|
||||
Agent Boundaries automatically reads `config.yaml` from
|
||||
`~/.config/coder_boundary/` when it starts, so everyone who launches Agent
|
||||
Boundaries manually inside the workspace picks up the same configuration without
|
||||
extra flags. This is especially convenient for managing extensive allow lists in
|
||||
version control.
|
||||
|
||||
### Configuration Parameters
|
||||
|
||||
- `log_dir` defines where boundary writes log files
|
||||
- `log_level` defines the verbosity at which requests are logged. Boundary uses the following verbosity levels:
|
||||
- `WARN`: logs only requests that have been blocked by Boundary
|
||||
- `log_level` defines the verbosity at which requests are logged. Agent
|
||||
Boundaries uses the following verbosity levels:
|
||||
- `WARN`: logs only requests that have been blocked by Agent Boundaries
|
||||
- `INFO`: logs all requests at a high level
|
||||
- `DEBUG`: logs all requests in detail
|
||||
- `proxy_port` defines the port used by the HTTP proxy.
|
||||
- `allowlist` defines the URLs that the agent can access, in addition to the default URLs required for the agent to work. Rules use the format `"key=value [key=value ...]"`:
|
||||
- `allowlist` defines the URLs that the agent can access, in addition to the
|
||||
default URLs required for the agent to work. Rules use the format
|
||||
`"key=value [key=value ...]"`:
|
||||
- `domain=github.com` - allows the domain and all its subdomains
|
||||
- `domain=*.github.com` - allows only subdomains (the specific domain is excluded)
|
||||
- `method=GET,HEAD domain=api.github.com` - allows specific HTTP methods for a domain
|
||||
- `method=POST domain=api.example.com path=/users,/posts` - allows specific methods, domain, and paths
|
||||
- `domain=*.github.com` - allows only subdomains (the specific domain is
|
||||
excluded)
|
||||
- `method=GET,HEAD domain=api.github.com` - allows specific HTTP methods for a
|
||||
domain
|
||||
- `method=POST domain=api.example.com path=/users,/posts` - allows specific
|
||||
methods, domain, and paths
|
||||
- `path=/api/v1/*,/api/v2/*` - allows specific URL paths
|
||||
|
||||
For detailed information about the rules engine and how to construct allowlist rules, see the [rules engine documentation](./rules-engine.md).
|
||||
For detailed information about the rules engine and how to construct allowlist
|
||||
rules, see the [rules engine documentation](./rules-engine.md).
|
||||
|
||||
You can also run Agent Boundaries directly in your workspace and configure it per template. You can do so by installing the [binary](https://github.com/coder/boundary) into the workspace image or at start-up. You can do so with the following command:
|
||||
You can also run Agent Boundaries directly in your workspace and configure it
|
||||
per template. You can do so by installing the
|
||||
[binary](https://github.com/coder/boundary) into the workspace image or at
|
||||
start-up. You can do so with the following command:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/coder/boundary/main/install.sh | bash
|
||||
```
|
||||
```
|
||||
|
||||
## Jail Types
|
||||
|
||||
Boundary supports two different jail types for process isolation, each with different characteristics and requirements:
|
||||
Agent Boundaries supports two different jail types for process isolation, each
|
||||
with different characteristics and requirements:
|
||||
|
||||
1. **nsjail** - Uses Linux namespaces for isolation. This is the default jail type and provides network namespace isolation. See [nsjail documentation](./nsjail.md) for detailed information about runtime requirements and Docker configuration.
|
||||
1. **nsjail** - Uses Linux namespaces for isolation. This is the default jail
|
||||
type and provides network namespace isolation. See
|
||||
[nsjail documentation](./nsjail.md) for detailed information about runtime
|
||||
requirements and Docker configuration.
|
||||
|
||||
2. **landjail** - Uses Landlock V4 for network isolation. This provides network isolation through the Landlock Linux Security Module (LSM) without requiring network namespace capabilities. See [landjail documentation](./landjail.md) for implementation details.
|
||||
2. **landjail** - Uses Landlock V4 for network isolation. This provides network
|
||||
isolation through the Landlock Linux Security Module (LSM) without requiring
|
||||
network namespace capabilities. See [landjail documentation](./landjail.md)
|
||||
for implementation details.
|
||||
|
||||
The choice of jail type depends on your security requirements, available Linux capabilities, and runtime environment. Both nsjail and landjail provide network isolation, but they use different underlying mechanisms. nsjail uses Linux namespaces, while landjail uses Landlock V4. Landjail may be preferred in environments where namespace capabilities are limited or unavailable.
|
||||
The choice of jail type depends on your security requirements, available Linux
|
||||
capabilities, and runtime environment. Both nsjail and landjail provide network
|
||||
isolation, but they use different underlying mechanisms. nsjail uses Linux
|
||||
namespaces, while landjail uses Landlock V4. Landjail may be preferred in
|
||||
environments where namespace capabilities are limited or unavailable.
|
||||
|
||||
## Implementation Comparison: Namespaces+iptables vs Landlock V4
|
||||
|
||||
@@ -118,29 +158,31 @@ The choice of jail type depends on your security requirements, available Linux c
|
||||
|
||||
## Audit Logs
|
||||
|
||||
Agent Boundaries stream audit logs to the Coder control plane, providing centralized
|
||||
visibility into HTTP requests made within workspaces—whether from AI agents or ad-hoc
|
||||
commands run with `boundary`.
|
||||
Agent Boundaries stream audit logs to the Coder control plane, providing
|
||||
centralized visibility into HTTP requests made within workspaces—whether from AI
|
||||
agents or ad-hoc commands run with `boundary`.
|
||||
|
||||
Audit logs are independent of application logs:
|
||||
|
||||
- **Audit logs** record Boundary's policy decisions: whether each HTTP request was
|
||||
allowed or denied based on the allowlist rules. These are always sent to the control
|
||||
plane regardless of Boundary's configured log level.
|
||||
- **Application logs** are Boundary's operational logs written locally to the workspace.
|
||||
These include startup messages, internal errors, and debugging information controlled
|
||||
by the `log_level` setting.
|
||||
- **Audit logs** record Agent Boundaries' policy decisions: whether each HTTP
|
||||
request was allowed or denied based on the allowlist rules. These are always
|
||||
sent to the control plane regardless of Agent Boundaries' configured log
|
||||
level.
|
||||
- **Application logs** are Agent Boundaries' operational logs written locally to
|
||||
the workspace. These include startup messages, internal errors, and debugging
|
||||
information controlled by the `log_level` setting.
|
||||
|
||||
For example, if a request to `api.example.com` is allowed by Boundary but the remote
|
||||
server returns a 500 error, the audit log records `decision=allow` because Boundary
|
||||
permitted the request. The HTTP response status is not tracked in audit logs.
|
||||
For example, if a request to `api.example.com` is allowed by Agent Boundaries
|
||||
but the remote server returns a 500 error, the audit log records
|
||||
`decision=allow` because Agent Boundaries permitted the request. The HTTP
|
||||
response status is not tracked in audit logs.
|
||||
|
||||
> [!NOTE]
|
||||
> Requires Coder v2.30+ and Boundary v0.5.2+.
|
||||
> Requires Coder v2.30+ and Agent Boundaries v0.5.2+.
|
||||
|
||||
### Audit Log Contents
|
||||
|
||||
Each boundary audit log entry includes:
|
||||
Each Agent Boundaries audit log entry includes:
|
||||
|
||||
| Field | Description |
|
||||
|-----------------------|-----------------------------------------------------------------------------------------|
|
||||
@@ -157,9 +199,9 @@ Each boundary audit log entry includes:
|
||||
|
||||
### Viewing Audit Logs
|
||||
|
||||
Boundary audit logs are emitted as structured log entries from the Coder server.
|
||||
You can collect and analyze these logs using any log aggregation system such as
|
||||
Grafana Loki.
|
||||
Agent Boundaries audit logs are emitted as structured log entries from the Coder
|
||||
server. You can collect and analyze these logs using any log aggregation system
|
||||
such as Grafana Loki.
|
||||
|
||||
Example of an allowed request (assuming stderr):
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# landjail Jail Type
|
||||
|
||||
landjail is Agent Boundaries' alternative jail type that uses Landlock V4 for
|
||||
network isolation.
|
||||
|
||||
## Overview
|
||||
|
||||
Agent Boundaries uses Landlock V4 to enforce network restrictions:
|
||||
|
||||
- All `bind` syscalls are forbidden
|
||||
- All `connect` syscalls are forbidden except to the port that is used by http
|
||||
proxy
|
||||
|
||||
This provides network isolation without requiring network namespace capabilities
|
||||
or special Docker permissions.
|
||||
@@ -0,0 +1,113 @@
|
||||
# nsjail Jail Type
|
||||
|
||||
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.
|
||||
|
||||
## Overview
|
||||
|
||||
nsjail leverages Linux namespace technology to isolate processes at the network
|
||||
level. When Agent Boundaries runs with nsjail, it creates a separate network
|
||||
namespace for the isolated process, allowing Agent Boundaries to intercept and
|
||||
filter all network traffic according to the configured policy.
|
||||
|
||||
This jail type requires Linux capabilities to create and manage network
|
||||
namespaces, which means it has specific runtime requirements when running in
|
||||
containerized environments like Docker.
|
||||
|
||||
## Architecture
|
||||
|
||||
<img width="1228" height="604" alt="Boundary" src="https://github.com/user-attachments/assets/1b7c8c5b-7b8f-4adf-8795-325bd28715c6" />
|
||||
|
||||
## Runtime & Permission Requirements for Running Agent Boundaries in Docker
|
||||
|
||||
This section describes the Linux capabilities and runtime configurations
|
||||
required to run Agent Boundaries with nsjail inside a Docker container.
|
||||
Requirements vary depending on the OCI runtime and the seccomp profile in use.
|
||||
|
||||
### 1. Default `runc` runtime with `CAP_NET_ADMIN`
|
||||
|
||||
When using Docker's default `runc` runtime, Agent Boundaries requires the
|
||||
container to have `CAP_NET_ADMIN`. This is the minimal capability needed for
|
||||
configuring virtual networking inside the container.
|
||||
|
||||
Docker's default seccomp profile may also block certain syscalls (such as
|
||||
`clone`) required for creating unprivileged network namespaces. If you encounter
|
||||
these restrictions, you may need to update or override the seccomp profile to
|
||||
allow these syscalls.
|
||||
|
||||
[see Docker Seccomp Profile Considerations](#docker-seccomp-profile-considerations)
|
||||
|
||||
### 2. Default `runc` runtime with `CAP_SYS_ADMIN` (testing only)
|
||||
|
||||
For development or testing environments, you may grant the container
|
||||
`CAP_SYS_ADMIN`, which implicitly bypasses many of the restrictions in Docker's
|
||||
default seccomp profile.
|
||||
|
||||
- Agent Boundaries does not require `CAP_SYS_ADMIN` itself.
|
||||
- However, Docker's default seccomp policy commonly blocks namespace-related
|
||||
syscalls unless `CAP_SYS_ADMIN` is present.
|
||||
- Granting `CAP_SYS_ADMIN` enables Agent Boundaries to run without modifying the
|
||||
seccomp profile.
|
||||
|
||||
⚠️ Warning: `CAP_SYS_ADMIN` is extremely powerful and should not be used in
|
||||
production unless absolutely necessary.
|
||||
|
||||
### 3. `sysbox-runc` runtime with `CAP_NET_ADMIN`
|
||||
|
||||
When using the `sysbox-runc` runtime (from Nestybox), Agent Boundaries can run
|
||||
with only:
|
||||
|
||||
- `CAP_NET_ADMIN`
|
||||
|
||||
The sysbox-runc runtime provides more complete support for unprivileged user
|
||||
namespaces and nested containerization, which typically eliminates the need for
|
||||
seccomp profile modifications.
|
||||
|
||||
## Docker Seccomp Profile Considerations
|
||||
|
||||
Docker's default seccomp profile frequently blocks the `clone` syscall, which is
|
||||
required by Agent Boundaries when creating unprivileged network namespaces. If
|
||||
the `clone` syscall is denied, Agent Boundaries will fail to start.
|
||||
|
||||
To address this, you may need to modify or override the seccomp profile used by
|
||||
your container to explicitly allow the required `clone` variants.
|
||||
|
||||
You can find the default Docker seccomp profile for your Docker version here
|
||||
(specify your docker version):
|
||||
|
||||
https://github.com/moby/moby/blob/v25.0.13/profiles/seccomp/default.json#L628-L635
|
||||
|
||||
If the profile blocks the necessary `clone` syscall arguments, you can provide a
|
||||
custom seccomp profile that adds an allow rule like the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"names": ["clone"],
|
||||
"action": "SCMP_ACT_ALLOW"
|
||||
}
|
||||
```
|
||||
|
||||
This example unblocks the clone syscall entirely.
|
||||
|
||||
### Example: Overriding the Docker Seccomp Profile
|
||||
|
||||
To use a custom seccomp profile, start by downloading the default profile for
|
||||
your Docker version:
|
||||
|
||||
https://github.com/moby/moby/blob/v25.0.13/profiles/seccomp/default.json#L628-L635
|
||||
|
||||
Save it locally as seccomp-v25.0.13.json, then insert the clone allow rule shown
|
||||
above (or add "clone" to the list of allowed syscalls).
|
||||
|
||||
Once updated, you can run the container with the custom seccomp profile:
|
||||
|
||||
```bash
|
||||
docker run -it \
|
||||
--cap-add=NET_ADMIN \
|
||||
--security-opt seccomp=seccomp-v25.0.13.json \
|
||||
test bash
|
||||
```
|
||||
|
||||
This instructs Docker to load your modified seccomp profile while granting only
|
||||
the minimal required capability (`CAP_NET_ADMIN`).
|
||||
+20
-13
@@ -2,15 +2,20 @@
|
||||
|
||||
## Overview
|
||||
|
||||
The `rulesengine` package provides a flexible rule-based filtering system for HTTP/HTTPS requests. Rules use a simple key-value syntax with support for wildcards and multiple values.
|
||||
The `rulesengine` package provides a flexible rule-based filtering system for
|
||||
HTTP/HTTPS requests. Rules use a simple key-value syntax with support for
|
||||
wildcards and multiple values.
|
||||
|
||||
### Basic Syntax
|
||||
|
||||
Rules follow the format: `key=value [key=value ...]` with three supported keys:
|
||||
|
||||
- **`method`**: HTTP method(s) - Any HTTP method (e.g., `GET`, `POST`, `PUT`, `DELETE`), `*` (all methods), or comma-separated list
|
||||
- **`domain`**: Domain/hostname pattern - `github.com`, `*.example.com`, `*` (all domains)
|
||||
- **`path`**: URL path pattern - `/api/users`, `/api/*/users`, `*` (all paths), or comma-separated list
|
||||
- **`method`**: HTTP method(s) - Any HTTP method (e.g., `GET`, `POST`, `PUT`,
|
||||
`DELETE`), `*` (all methods), or comma-separated list
|
||||
- **`domain`**: Domain/hostname pattern - `github.com`, `*.example.com`, `*`
|
||||
(all domains)
|
||||
- **`path`**: URL path pattern - `/api/users`, `/api/*/users`, `*` (all paths),
|
||||
or comma-separated list
|
||||
|
||||
**Key behavior**:
|
||||
|
||||
@@ -23,11 +28,11 @@ Rules follow the format: `key=value [key=value ...]` with three supported keys:
|
||||
|
||||
```yaml
|
||||
allowlist:
|
||||
- domain=github.com # All methods, all paths for github.com (exact match)
|
||||
- domain=*.github.com # All subdomains of github.com
|
||||
- method=GET,POST domain=api.example.com # GET/POST to api.example.com (exact match)
|
||||
- domain=api.example.com path=/users,/posts # Multiple paths
|
||||
- method=GET domain=github.com path=/api/* # All three keys
|
||||
- domain=github.com # All methods, all paths for github.com (exact match)
|
||||
- domain=*.github.com # All subdomains of github.com
|
||||
- method=GET,POST domain=api.example.com # GET/POST to api.example.com (exact match)
|
||||
- domain=api.example.com path=/users,/posts # Multiple paths
|
||||
- method=GET domain=github.com path=/api/* # All three keys
|
||||
```
|
||||
|
||||
---
|
||||
@@ -49,7 +54,8 @@ The `*` wildcard matches domain labels (parts separated by dots).
|
||||
|
||||
- Patterns without `*` match **exactly** (no automatic subdomain matching)
|
||||
- `*.example.com` matches one or more subdomain levels
|
||||
- To match both base domain and subdomains, use separate rules: `domain=github.com` and `domain=*.github.com`
|
||||
- To match both base domain and subdomains, use separate rules:
|
||||
`domain=github.com` and `domain=*.github.com`
|
||||
- Domain patterns **cannot end with asterisk**
|
||||
|
||||
---
|
||||
@@ -71,7 +77,8 @@ The `*` wildcard matches path segments (parts separated by slashes).
|
||||
|
||||
- `*` matches **exactly one segment** (except at the end)
|
||||
- `*` at the **end** matches **one or more segments** (special behavior)
|
||||
- `*` must match an entire segment (cannot be part of a segment like `/api/user*`)
|
||||
- `*` must match an entire segment (cannot be part of a segment like
|
||||
`/api/user*`)
|
||||
|
||||
---
|
||||
|
||||
@@ -96,5 +103,5 @@ allowlist:
|
||||
- domain=api.example.com path=/api,/api/*
|
||||
```
|
||||
|
||||
`NOTE`: The pattern `/api/*` does not include the base path `/api`.
|
||||
To match both, use `path=/api,/api/*`.
|
||||
`NOTE`: The pattern `/api/*` does not include the base path `/api`. To match
|
||||
both, use `path=/api,/api/*`.
|
||||
@@ -2,24 +2,32 @@
|
||||
|
||||
## Recommended Versions
|
||||
|
||||
It's recommended to use **Coder v2.30.0 or newer** and **Claude Code module v4.7.0 or newer**.
|
||||
It's recommended to use **Coder v2.30.0 or newer** and **Claude Code module
|
||||
v4.7.0 or newer**.
|
||||
|
||||
### Coder v2.30.0+
|
||||
|
||||
Since Coder v2.30.0, Boundary is embedded inside the Coder binary, and you don't need to install it separately. The `coder boundary` subcommand is available directly from the Coder CLI.
|
||||
Since Coder v2.30.0, Agent Boundaries is embedded inside the Coder binary, and
|
||||
you don't need to install it separately. The `coder boundary` subcommand is
|
||||
available directly from the Coder CLI.
|
||||
|
||||
### Claude Code Module v4.7.0+
|
||||
|
||||
Since Claude Code module v4.7.0, the embedded Coder Boundary subcommand is used by default. This means you don't need to set `boundary_version`; the boundary version is tied to your Coder version.
|
||||
Since Claude Code module v4.7.0, the embedded `coder boundary` subcommand is
|
||||
used by default. This means you don't need to set `boundary_version`; the
|
||||
boundary version is tied to your Coder version.
|
||||
|
||||
## Compatibility with Older Versions
|
||||
|
||||
### Using Coder Before v2.30.0 with Claude Code Module v4.7.0+
|
||||
|
||||
If you're using Coder before v2.30.0 with Claude Code module v4.7.0 or newer, the `coder boundary` subcommand isn't available in your Coder installation. In this case, you need to:
|
||||
If you're using Coder before v2.30.0 with Claude Code module v4.7.0 or newer,
|
||||
the `coder boundary` subcommand isn't available in your Coder installation. In
|
||||
this case, you need to:
|
||||
|
||||
1. Set `use_boundary_directly = true` in your Terraform module configuration
|
||||
2. Explicitly set `boundary_version` to specify which Boundary version to install
|
||||
2. Explicitly set `boundary_version` to specify which Agent Boundaries version
|
||||
to install
|
||||
|
||||
Example configuration:
|
||||
|
||||
@@ -35,7 +43,9 @@ module "claude-code" {
|
||||
|
||||
### Using Claude Code Module Before v4.7.0
|
||||
|
||||
If you're using Claude Code module before v4.7.0, the module expects to use Boundary directly. You need to explicitly set `boundary_version` in your Terraform configuration:
|
||||
If you're using Claude Code module before v4.7.0, the module expects to use
|
||||
Agent Boundaries directly. You need to explicitly set `boundary_version` in your
|
||||
Terraform configuration:
|
||||
|
||||
```tf
|
||||
module "claude-code" {
|
||||
@@ -1,67 +1,113 @@
|
||||
# AI Governance Add-On (Premium)
|
||||
|
||||
Coder Workspaces already lets teams run AI tools like [Cursor](https://registry.coder.com/modules/coder/cursor) and [Claude Code](https://registry.coder.com/modules/coder/claude-code) inside their development environments. As adoption grows, many enterprises also need observability, management, and policy controls to support secure and auditable AI rollouts.
|
||||
Coder Workspaces already lets teams run AI tools like
|
||||
[Cursor](https://registry.coder.com/modules/coder/cursor) and
|
||||
[Claude Code](https://registry.coder.com/modules/coder/claude-code) inside their
|
||||
development environments. As adoption grows, many enterprises also need
|
||||
observability, management, and policy controls to support secure and auditable
|
||||
AI rollouts.
|
||||
|
||||
Coder’s AI Governance Add-On for Premium licenses includes a set of features that help organizations safely roll out AI tooling at scale:
|
||||
Coder’s AI Governance Add-On for Premium licenses includes a set of features
|
||||
that help organizations safely roll out AI tooling at scale:
|
||||
|
||||
- [AI Bridge](./ai-bridge/index.md): LLM gateway to audit AI sessions, central MCP server management, and policy enforcement
|
||||
- [Boundaries](./boundary/agent-boundary.md): Process-level firewalls for agents, restricting which domains can be accessed by AI agents
|
||||
- [Additional Tasks Use (via Agent Workspace Builds)](#how-coder-tasks-usage-is-measured): Additional allowance of Agent Workspace Builds for continued use of Coder Tasks.
|
||||
- [AI Bridge](./ai-bridge/index.md): LLM gateway to audit AI sessions, central
|
||||
MCP server management, and policy enforcement
|
||||
- [Agent Boundaries](./agent-boundaries/index.md): Process-level firewalls for
|
||||
agents, restricting which domains can be accessed by AI agents
|
||||
- [Additional Tasks Use (via Agent Workspace Builds)](#how-coder-tasks-usage-is-measured):
|
||||
Additional allowance of Agent Workspace Builds for continued use of Coder
|
||||
Tasks.
|
||||
|
||||
## Who should use the AI Governance Add-On
|
||||
|
||||
The AI Governance Add-On is for teams that want to extend that platform to support AI-powered IDEs and coding agents in a controlled, observable way.
|
||||
The AI Governance Add-On is for teams that want to extend that platform to
|
||||
support AI-powered IDEs and coding agents in a controlled, observable way.
|
||||
|
||||
It's a good fit if you're:
|
||||
|
||||
- Rolling out AI-powered IDEs like Cursor and AI coding agents like Claude Code across teams
|
||||
- Looking to centrally observe, audit, and govern AI activity in Coder Workspaces
|
||||
- Rolling out AI-powered IDEs like Cursor and AI coding agents like Claude Code
|
||||
across teams
|
||||
- Looking to centrally observe, audit, and govern AI activity in Coder
|
||||
Workspaces
|
||||
- Managing AI workflows against sensitive or regulated codebases
|
||||
- Expanding the use of Coder Tasks for AI-driven background work
|
||||
|
||||
If you already use other AI governance tools, such as third-party LLM gateways or vendor-managed policies, you can continue using them. Coder Workspaces can still serve as the backend for development environments and AI workflows, with or without the AI Governance Add-On.
|
||||
If you already use other AI governance tools, such as third-party LLM gateways
|
||||
or vendor-managed policies, you can continue using them. Coder Workspaces can
|
||||
still serve as the backend for development environments and AI workflows, with
|
||||
or without the AI Governance Add-On.
|
||||
|
||||
## Use cases for AI Governance
|
||||
|
||||
Organizations adopting AI coding tools at scale often encounter operational and security challenges that traditional developer tooling doesn't address.
|
||||
Organizations adopting AI coding tools at scale often encounter operational and
|
||||
security challenges that traditional developer tooling doesn't address.
|
||||
|
||||
### Auditing AI activity across teams
|
||||
|
||||
Without centralized monitoring, teams have no way to understand how AI tools are being used across the organization. AI Bridge provides audit trails of prompts, token usage, and tool invocations, giving administrators insight into AI adoption patterns and potential issues.
|
||||
Without centralized monitoring, teams have no way to understand how AI tools are
|
||||
being used across the organization. AI Bridge provides audit trails of prompts,
|
||||
token usage, and tool invocations, giving administrators insight into AI
|
||||
adoption patterns and potential issues.
|
||||
|
||||
### Restricting agent network and command access
|
||||
|
||||
AI agents can make arbitrary network requests, potentially accessing unauthorized services or exfiltrating data. They can also execute destructive commands within a workspace. Agent Boundaries enforce process-level policies that restrict which domains agents can reach and what actions they can perform, preventing unintended data exposure and destructive operations like `rm -rf`.
|
||||
AI agents can make arbitrary network requests, potentially accessing
|
||||
unauthorized services or exfiltrating data. They can also execute destructive
|
||||
commands within a workspace. Agent Boundaries enforce process-level policies
|
||||
that restrict which domains agents can reach and what actions they can perform,
|
||||
preventing unintended data exposure and destructive operations like `rm -rf`.
|
||||
|
||||
### Centralizing API key management
|
||||
|
||||
Managing individual API keys for AI providers across hundreds of developers creates security risks and administrative overhead. AI Bridge centralizes authentication so users authenticate through Coder, eliminating the need to distribute and rotate provider API keys.
|
||||
Managing individual API keys for AI providers across hundreds of developers
|
||||
creates security risks and administrative overhead. AI Bridge centralizes
|
||||
authentication so users authenticate through Coder, eliminating the need to
|
||||
distribute and rotate provider API keys.
|
||||
|
||||
### Standardizing MCP tools and servers
|
||||
|
||||
Different teams may use different MCP servers and tools with varying security postures. AI Bridge enables centralized MCP administration, allowing organizations to define approved tools and servers that all users can access.
|
||||
Different teams may use different MCP servers and tools with varying security
|
||||
postures. AI Bridge enables centralized MCP administration, allowing
|
||||
organizations to define approved tools and servers that all users can access.
|
||||
|
||||
### Measuring AI adoption and spend
|
||||
|
||||
Without usage data, it's hard to justify AI tooling investments or identify high-leverage use cases. AI Bridge captures metrics on token spend, adoption rates, and usage patterns to inform decisions about AI strategy.
|
||||
Without usage data, it's hard to justify AI tooling investments or identify
|
||||
high-leverage use cases. AI Bridge captures metrics on token spend, adoption
|
||||
rates, and usage patterns to inform decisions about AI strategy.
|
||||
|
||||
## GA status and availability
|
||||
|
||||
Starting with Coder v2.30 (February 2026), AI Bridge and Agent Boundaries are generally available as part of the AI Governance Add-On.
|
||||
Starting with Coder v2.30 (February 2026), AI Bridge and Agent Boundaries are
|
||||
generally available as part of the AI Governance Add-On.
|
||||
|
||||
If you've been experimenting with these features in earlier releases, you'll see a notification banner in your deployment in v2.30. This banner is a reminder that these features have moved out of beta and are now included with the AI Governance Add-On.
|
||||
If you've been experimenting with these features in earlier releases, you'll see
|
||||
a notification banner in your deployment in v2.30. This banner is a reminder
|
||||
that these features have moved out of beta and are now included with the AI
|
||||
Governance Add-On.
|
||||
|
||||
In v2.30, this notification is informational only. A future Coder release will require the add-on to continue using AI Bridge and Agent Boundaries.
|
||||
In v2.30, this notification is informational only. A future Coder release will
|
||||
require the add-on to continue using AI Bridge and Agent Boundaries.
|
||||
|
||||
To learn more about enabling the AI Governance Add-On, pricing, or trial options, reach out to your [Coder account team](https://coder.com/contact/sales).
|
||||
To learn more about enabling the AI Governance Add-On, pricing, or trial
|
||||
options, reach out to your
|
||||
[Coder account team](https://coder.com/contact/sales).
|
||||
|
||||
## How Coder Tasks usage is measured
|
||||
|
||||
The usage metric used to measure Coder Tasks consumption is called **Agent Workspace Builds** (prev. "managed agents").
|
||||
The usage metric used to measure Coder Tasks consumption is called **Agent
|
||||
Workspace Builds** (prev. "managed agents").
|
||||
|
||||
An Agent Workspace Build is counted each time a workspace is started specifically for a coding agent to independently work on a Coder Task. Most of the work in this workspace is performed by the agent, not a human developer. Each Coder Task starts its own workspace, and the usage meter counts one Agent Workspace Build.
|
||||
An Agent Workspace Build is counted each time a workspace is started
|
||||
specifically for a coding agent to independently work on a Coder Task. Most of
|
||||
the work in this workspace is performed by the agent, not a human developer.
|
||||
Each Coder Task starts its own workspace, and the usage meter counts one Agent
|
||||
Workspace Build.
|
||||
|
||||
Traditional Coder Workspaces started manually by developers or scheduled to auto-start do not count as an Agent Workspace Build. These are considered daily-driver development environments where developers co-exist with their IDEs and coding assistants.
|
||||
Traditional Coder Workspaces started manually by developers or scheduled to
|
||||
auto-start do not count as an Agent Workspace Build. These are considered
|
||||
daily-driver development environments where developers co-exist with their IDEs
|
||||
and coding assistants.
|
||||
|
||||
### Scenarios
|
||||
|
||||
@@ -72,14 +118,23 @@ Traditional Coder Workspaces started manually by developers or scheduled to auto
|
||||
| Developer resumes an old Coder Task order to continue prototyping | Yes |
|
||||
| Developer starts a workspace for use with VS Code and Jupyter | No |
|
||||
| Developer creates a workspace for use with Cursor and Claude Code CLI | No |
|
||||
| Developer creates a workspace for use with Coder AI Bridge and Boundaries | No |
|
||||
| Developer creates a workspace for use with Coder AI Bridge and Agent Boundaries | No |
|
||||
|
||||
In the future, additional capabilities for managing agents (beyond Coder Tasks) may also consume agent workspace builds.
|
||||
In the future, additional capabilities for managing agents (beyond Coder Tasks)
|
||||
may also consume agent workspace builds.
|
||||
|
||||
### Agent Workspace Build Limits
|
||||
|
||||
Without proper controls and sandboxing, it is not recommended to open up Coder Tasks to a large audience in the enterprise. Coder Premium deployments include 1,000 Agent Workspace Builds, primarily for proof-of-concept use and basic workflows.
|
||||
Without proper controls and sandboxing, it is not recommended to open up Coder
|
||||
Tasks to a large audience in the enterprise. Coder Premium deployments include
|
||||
1,000 Agent Workspace Builds, primarily for proof-of-concept use and basic
|
||||
workflows.
|
||||
|
||||
Our [AI Governance Add-On](./ai-governance.md) includes a shared usage pool of Agent Workspace Builds for automated workflows, along with limits that scale proportionately with user count. Usage counts are measured and sent to Coder via [usage data reporting](./usage-data-reporting.md). Coder Tasks or other AI features do not break when you run over the limit.
|
||||
Our [AI Governance Add-On](./ai-governance.md) includes a shared usage pool of
|
||||
Agent Workspace Builds for automated workflows, along with limits that scale
|
||||
proportionately with user count. Usage counts are measured and sent to Coder via
|
||||
[usage data reporting](./usage-data-reporting.md). Coder Tasks or other AI
|
||||
features do not break when you run over the limit.
|
||||
|
||||
If you are approaching your deployment-wide limits, [contact us](https://coder.com/contact) to discuss your use case with our team.
|
||||
If you are approaching your deployment-wide limits,
|
||||
[contact us](https://coder.com/contact) to discuss your use case with our team.
|
||||
|
||||
@@ -1,12 +0,0 @@
|
||||
# landjail Jail Type
|
||||
|
||||
landjail is Boundary's alternative jail type that uses Landlock V4 for network isolation.
|
||||
|
||||
## Overview
|
||||
|
||||
Boundary uses Landlock V4 to enforce network restrictions:
|
||||
|
||||
- All `bind` syscalls are forbidden
|
||||
- All `connect` syscalls are forbidden except to the port that is used by http proxy
|
||||
|
||||
This provides network isolation without requiring network namespace capabilities or special Docker permissions.
|
||||
@@ -1,85 +0,0 @@
|
||||
# nsjail Jail Type
|
||||
|
||||
nsjail is Boundary's 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.
|
||||
|
||||
## Overview
|
||||
|
||||
nsjail leverages Linux namespace technology to isolate processes at the network level. When Boundary runs with nsjail, it creates a separate network namespace for the isolated process, allowing Boundary to intercept and filter all network traffic according to the configured policy.
|
||||
|
||||
This jail type requires Linux capabilities to create and manage network namespaces, which means it has specific runtime requirements when running in containerized environments like Docker.
|
||||
|
||||
## Architecture
|
||||
|
||||
<img width="1228" height="604" alt="Boundary" src="https://github.com/user-attachments/assets/1b7c8c5b-7b8f-4adf-8795-325bd28715c6" />
|
||||
|
||||
## Runtime & Permission Requirements for Running the Boundary in Docker
|
||||
|
||||
This section describes the Linux capabilities and runtime configurations required to run the Agent Boundary with nsjail inside a Docker container. Requirements vary depending on the OCI runtime and the seccomp profile in use.
|
||||
|
||||
### 1. Default `runc` runtime with `CAP_NET_ADMIN`
|
||||
|
||||
When using Docker's default `runc` runtime, the Boundary requires the container to have `CAP_NET_ADMIN`. This is the minimal capability needed for configuring virtual networking inside the container.
|
||||
|
||||
Docker's default seccomp profile may also block certain syscalls (such as `clone`) required for creating unprivileged network namespaces. If you encounter these restrictions, you may need to update or override the seccomp profile to allow these syscalls.
|
||||
|
||||
[see Docker Seccomp Profile Considerations](#docker-seccomp-profile-considerations)
|
||||
|
||||
### 2. Default `runc` runtime with `CAP_SYS_ADMIN` (testing only)
|
||||
|
||||
For development or testing environments, you may grant the container `CAP_SYS_ADMIN`, which implicitly bypasses many of the restrictions in Docker's default seccomp profile.
|
||||
|
||||
- The Boundary does not require `CAP_SYS_ADMIN` itself.
|
||||
- However, Docker's default seccomp policy commonly blocks namespace-related syscalls unless `CAP_SYS_ADMIN` is present.
|
||||
- Granting `CAP_SYS_ADMIN` enables the Boundary to run without modifying the seccomp profile.
|
||||
|
||||
⚠️ Warning: `CAP_SYS_ADMIN` is extremely powerful and should not be used in production unless absolutely necessary.
|
||||
|
||||
### 3. `sysbox-runc` runtime with `CAP_NET_ADMIN`
|
||||
|
||||
When using the `sysbox-runc` runtime (from Nestybox), the Boundary can run with only:
|
||||
|
||||
- `CAP_NET_ADMIN`
|
||||
|
||||
The sysbox-runc runtime provides more complete support for unprivileged user namespaces and nested containerization, which typically eliminates the need for seccomp profile modifications.
|
||||
|
||||
## Docker Seccomp Profile Considerations
|
||||
|
||||
Docker's default seccomp profile frequently blocks the `clone` syscall, which is required by the Boundary when creating unprivileged network namespaces. If the `clone` syscall is denied, the Boundary will fail to start.
|
||||
|
||||
To address this, you may need to modify or override the seccomp profile used by your container to explicitly allow the required `clone` variants.
|
||||
|
||||
You can find the default Docker seccomp profile for your Docker version here (specify your docker version):
|
||||
|
||||
https://github.com/moby/moby/blob/v25.0.13/profiles/seccomp/default.json#L628-L635
|
||||
|
||||
If the profile blocks the necessary `clone` syscall arguments, you can provide a custom seccomp profile that adds an allow rule like the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"names": [
|
||||
"clone"
|
||||
],
|
||||
"action": "SCMP_ACT_ALLOW"
|
||||
}
|
||||
```
|
||||
|
||||
This example unblocks the clone syscall entirely.
|
||||
|
||||
### Example: Overriding the Docker Seccomp Profile
|
||||
|
||||
To use a custom seccomp profile, start by downloading the default profile for your Docker version:
|
||||
|
||||
https://github.com/moby/moby/blob/v25.0.13/profiles/seccomp/default.json#L628-L635
|
||||
|
||||
Save it locally as seccomp-v25.0.13.json, then insert the clone allow rule shown above (or add "clone" to the list of allowed syscalls).
|
||||
|
||||
Once updated, you can run the container with the custom seccomp profile:
|
||||
|
||||
```bash
|
||||
docker run -it \
|
||||
--cap-add=NET_ADMIN \
|
||||
--security-opt seccomp=seccomp-v25.0.13.json \
|
||||
test bash
|
||||
```
|
||||
|
||||
This instructs Docker to load your modified seccomp profile while granting only the minimal required capability (`CAP_NET_ADMIN`).
|
||||
+30
-9
@@ -1,27 +1,48 @@
|
||||
# Run AI Coding Agents in Coder
|
||||
|
||||
Learn how to run & manage coding agents with Coder, both alongside existing workspaces and for background task execution.
|
||||
Learn how to run & manage coding agents with Coder, both alongside existing
|
||||
workspaces and for background task execution.
|
||||
|
||||
## Agents in the IDE
|
||||
|
||||
Coder [integrates with IDEs](../user-guides/workspace-access/index.md) such as Cursor, Windsurf, and Zed that include built-in coding agents to work alongside developers. Additionally, template admins can [pre-install extensions](https://registry.coder.com/modules/coder/vscode-web) for agents such as GitHub Copilot and Roo Code.
|
||||
Coder [integrates with IDEs](../user-guides/workspace-access/index.md) such as
|
||||
Cursor, Windsurf, and Zed that include built-in coding agents to work alongside
|
||||
developers. Additionally, template admins can
|
||||
[pre-install extensions](https://registry.coder.com/modules/coder/vscode-web)
|
||||
for agents such as GitHub Copilot and Roo Code.
|
||||
|
||||
These agents work well inside existing Coder workspaces as they can simply be enabled via an extension or are built-into the editor.
|
||||
These agents work well inside existing Coder workspaces as they can simply be
|
||||
enabled via an extension or are built-into the editor.
|
||||
|
||||
## Agents with Coder Tasks
|
||||
|
||||
In cases where the IDE is secondary, such as prototyping or long-running background jobs, agents like Claude Code or Aider are better for the job and new SaaS interfaces like [Devin](https://devin.ai) and [ChatGPT Codex](https://openai.com/index/introducing-codex/) are emerging.
|
||||
In cases where the IDE is secondary, such as prototyping or long-running
|
||||
background jobs, agents like Claude Code or Aider are better for the job and new
|
||||
SaaS interfaces like [Devin](https://devin.ai) and
|
||||
[ChatGPT Codex](https://openai.com/index/introducing-codex/) are emerging.
|
||||
|
||||
[Coder Tasks](./tasks.md) is an interface inside Coder to run and manage coding agents with a chat-based UI. Unlike SaaS-based products, Coder Tasks is self-hosted (included in your Coder deployment) and allows you to run any terminal-based agent such as Claude Code or Codex's Open Source CLI.
|
||||
[Coder Tasks](./tasks.md) is an interface inside Coder to run and manage coding
|
||||
agents with a chat-based UI. Unlike SaaS-based products, Coder Tasks is
|
||||
self-hosted (included in your Coder deployment) and allows you to run any
|
||||
terminal-based agent such as Claude Code or Codex's Open Source CLI.
|
||||
|
||||
|
||||
|
||||
[Learn more about Coder Tasks](./tasks.md) for best practices and how to get started.
|
||||
[Learn more about Coder Tasks](./tasks.md) for best practices and how to get
|
||||
started.
|
||||
|
||||
## Secure Your Workflows with Agent Boundaries (Beta)
|
||||
|
||||
AI agents can be powerful teammates, but must be treated as untrusted and unpredictable interns as opposed to tools. Without the right controls, they can go rogue.
|
||||
AI agents can be powerful teammates, but must be treated as untrusted and
|
||||
unpredictable interns as opposed to tools. Without the right controls, they can
|
||||
go rogue.
|
||||
|
||||
[Agent Boundaries](./boundary/agent-boundary.md) is a new tool that offers process-level safeguards that detect and prevent destructive actions. Unlike traditional mitigation methods like firewalls, service meshes, and RBAC systems, Agent Boundaries is an agent-aware, centralized control point that can either be embedded in the same secure Coder Workspaces that enterprises already trust, or used through an open source CLI.
|
||||
[Agent Boundaries](./agent-boundaries/index.md) is a new tool that offers
|
||||
process-level safeguards that detect and prevent destructive actions. Unlike
|
||||
traditional mitigation methods like firewalls, service meshes, and RBAC systems,
|
||||
Agent Boundaries is an agent-aware, centralized control point that can either be
|
||||
embedded in the same secure Coder Workspaces that enterprises already trust, or
|
||||
used through an open source CLI.
|
||||
|
||||
To learn more about features, implementation details, and how to get started, check out the [Agent Boundary documentation](./boundary/agent-boundary.md).
|
||||
To learn more about features, implementation details, and how to get started,
|
||||
check out the [Agent Boundaries documentation](./agent-boundaries/index.md).
|
||||
|
||||
@@ -4,10 +4,10 @@ environments.
|
||||
|
||||
## Use Trusted Models
|
||||
|
||||
Most agents can be configured to either use a local LLM (e.g.
|
||||
llama3), an agent proxy (e.g. OpenRouter), or a Cloud-Provided LLM (e.g. AWS
|
||||
Bedrock). Research which models you are comfortable with and configure your
|
||||
Coder templates to use those.
|
||||
Most agents can be configured to either use a local LLM (e.g. llama3), an agent
|
||||
proxy (e.g. OpenRouter), or a Cloud-Provided LLM (e.g. AWS Bedrock). Research
|
||||
which models you are comfortable with and configure your Coder templates to use
|
||||
those.
|
||||
|
||||
## Set up Firewalls and Proxies
|
||||
|
||||
@@ -19,10 +19,13 @@ not access or upload sensitive information.
|
||||
|
||||
Many agents require API keys to access external services. It is recommended to
|
||||
create a separate API key for your agent with the minimum permissions required.
|
||||
This will likely involve editing your template for Agents to set different scopes or tokens from the standard one.
|
||||
This will likely involve editing your template for Agents to set different
|
||||
scopes or tokens from the standard one.
|
||||
|
||||
Additional guidance and tooling is coming in future releases of Coder.
|
||||
|
||||
## Set Up Agent Boundaries
|
||||
|
||||
Agent Boundaries are process-level "agent firewalls" that lets you restrict and audit what AI agents can access within Coder workspaces. To learn more about this feature, see [Agent Boundary](./boundary/agent-boundary.md).
|
||||
Agent Boundaries are process-level "agent firewalls" that lets you restrict and
|
||||
audit what AI agents can access within Coder workspaces. To learn more about
|
||||
this feature, see [Agent Boundaries](./agent-boundaries/index.md).
|
||||
|
||||
@@ -2,45 +2,97 @@
|
||||
|
||||
## Guide Overview
|
||||
|
||||
Coder provides Extended Support Releases (ESR) bianually. This guide walks through upgrading from the initial Coder 2.24 ESR to our new 2.29 ESR. It will summarize key changes, highlight breaking updates, and provide a recommended upgrade process.
|
||||
Coder provides Extended Support Releases (ESR) bianually. This guide walks
|
||||
through upgrading from the initial Coder 2.24 ESR to our new 2.29 ESR. It will
|
||||
summarize key changes, highlight breaking updates, and provide a recommended
|
||||
upgrade process.
|
||||
|
||||
Read more about the ESR release process [here](./index.md#extended-support-release), and how Coder supports it.
|
||||
Read more about the ESR release process
|
||||
[here](./index.md#extended-support-release), and how Coder supports it.
|
||||
|
||||
## What's New in Coder 2.29
|
||||
|
||||
### Coder Tasks
|
||||
|
||||
Coder Tasks is an interface for running and interfacing with terminal-based coding agents like Claude Code and Codex, powered by Coder workspaces. Beginning in Coder 2.24, Tasks were introduced as an experimental feature that allowed administrators and developers to run long-lived or automated operations from templates. Over subsequent releases, Tasks matured significantly through UI refinement, improved reliability, and underlying task-status improvements in the server and database layers. By 2.29, Tasks were formally promoted to general availability, with full CLI support, a task-specific UI, and consistent visibility of task states across the dashboard. This transition establishes Tasks as a stable automation and job-execution primitive within Coder—particularly suited for long-running background operations like bug fixes, documentation generation, PR reviews, and testing/QA.For more information, read our documentation [here](https://coder.com/docs/ai-coder/tasks).
|
||||
Coder Tasks is an interface for running and interfacing with terminal-based
|
||||
coding agents like Claude Code and Codex, powered by Coder workspaces. Beginning
|
||||
in Coder 2.24, Tasks were introduced as an experimental feature that allowed
|
||||
administrators and developers to run long-lived or automated operations from
|
||||
templates. Over subsequent releases, Tasks matured significantly through UI
|
||||
refinement, improved reliability, and underlying task-status improvements in the
|
||||
server and database layers. By 2.29, Tasks were formally promoted to general
|
||||
availability, with full CLI support, a task-specific UI, and consistent
|
||||
visibility of task states across the dashboard. This transition establishes
|
||||
Tasks as a stable automation and job-execution primitive within
|
||||
Coder—particularly suited for long-running background operations like bug fixes,
|
||||
documentation generation, PR reviews, and testing/QA.For more information, read
|
||||
our documentation [here](https://coder.com/docs/ai-coder/tasks).
|
||||
|
||||
### AI Bridge
|
||||
|
||||
AI Bridge was introduced in 2.26, and is a smart gateway that acts as an intermediary between users' coding agents/IDEs and AI providers like OpenAI and Anthropic. It solves three key problems:
|
||||
AI Bridge was introduced in 2.26, and is a smart gateway that acts as an
|
||||
intermediary between users' coding agents/IDEs and AI providers like OpenAI and
|
||||
Anthropic. It solves three key problems:
|
||||
|
||||
- Centralized authentication/authorization management (users authenticate via Coder instead of managing individual API tokens)
|
||||
- Auditing and attribution of all AI interactions (whether autonomous or human-initiated)
|
||||
- Centralized authentication/authorization management (users authenticate via
|
||||
Coder instead of managing individual API tokens)
|
||||
- Auditing and attribution of all AI interactions (whether autonomous or
|
||||
human-initiated)
|
||||
- Secure communication between the Coder control plane and upstream AI APIs
|
||||
|
||||
This is a Premium/Beta feature that intercepts AI traffic to record prompts, token usage, and tool invocations. For more information, read our documentation [here](https://coder.com/docs/ai-coder/ai-bridge).
|
||||
This is a Premium/Beta feature that intercepts AI traffic to record prompts,
|
||||
token usage, and tool invocations. For more information, read our documentation
|
||||
[here](https://coder.com/docs/ai-coder/ai-bridge).
|
||||
|
||||
### Agent Boundaries
|
||||
|
||||
Agent Boundaries was introduced in 2.27 and is currently in Early Access. Agent Boundaries are process-level firewalls in Coder that restrict and audit what autonomous programs (like AI agents) can access and do within a workspace. They provide network policy enforcement—blocking specific domains and HTTP verbs to prevent data exfiltration—and write logs to the workspace for auditability. Boundaries support any terminal-based agent, including custom ones, and can be easily configured through existing Coder modules like the Claude Code module. For more information, read our documentation [here](https://coder.com/docs/ai-coder/agent-boundary).
|
||||
Agent Boundaries was introduced in 2.27 and is currently in Early Access. Agent
|
||||
Boundaries are process-level firewalls in Coder that restrict and audit what
|
||||
autonomous programs (like AI agents) can access and do within a workspace. They
|
||||
provide network policy enforcement—blocking specific domains and HTTP verbs to
|
||||
prevent data exfiltration—and write logs to the workspace for auditability.
|
||||
Boundaries support any terminal-based agent, including custom ones, and can be
|
||||
easily configured through existing Coder modules like the Claude Code module.
|
||||
For more information, read our documentation
|
||||
[here](../../ai-coder/agent-boundaries/index.md).
|
||||
|
||||
### Performance Enhancements
|
||||
|
||||
Performance, particularly at scale, improved across nearly every system layer. Database queries were optimized, several new indexes were added, and expensive migrations—such as migration 371—were reworked to complete faster on large deployments. Caching was introduced for Terraform installer files and workspace/agent lookups, reducing repeated calls. Notification performance improved through more efficient connection pooling. These changes collectively enable deployments with hundreds or thousands of workspaces to operate more smoothly and with lower resource contention.
|
||||
Performance, particularly at scale, improved across nearly every system layer.
|
||||
Database queries were optimized, several new indexes were added, and expensive
|
||||
migrations—such as migration 371—were reworked to complete faster on large
|
||||
deployments. Caching was introduced for Terraform installer files and
|
||||
workspace/agent lookups, reducing repeated calls. Notification performance
|
||||
improved through more efficient connection pooling. These changes collectively
|
||||
enable deployments with hundreds or thousands of workspaces to operate more
|
||||
smoothly and with lower resource contention.
|
||||
|
||||
### Server and API Updates
|
||||
|
||||
Core server capabilities expanded significantly across the releases. Prebuild workflows gained timestamp-driven invalidation via last_invalidated_at, expired API keys began being automatically purged, and new API key-scope documentation was introduced to help administrators understand authorization boundaries. New API endpoints were added, including the ability to modify a task prompt or look up tasks by name. Template developers benefited from new Terraform directory-persistence capabilities (opt-in on a per-template basis) and improved `protobuf` configuration metadata.
|
||||
Core server capabilities expanded significantly across the releases. Prebuild
|
||||
workflows gained timestamp-driven invalidation via last_invalidated_at, expired
|
||||
API keys began being automatically purged, and new API key-scope documentation
|
||||
was introduced to help administrators understand authorization boundaries. New
|
||||
API endpoints were added, including the ability to modify a task prompt or look
|
||||
up tasks by name. Template developers benefited from new Terraform
|
||||
directory-persistence capabilities (opt-in on a per-template basis) and improved
|
||||
`protobuf` configuration metadata.
|
||||
|
||||
### CLI Enhancements
|
||||
|
||||
The CLI gained substantial improvements between the two versions. Most notably, beginning in 2.29, Coder’s CLI now stores session tokens in the operating system keyring by default on macOS and Windows, enhancing credential security and reducing exposure from plaintext token storage. Users who rely on directly accessing the token file can opt out using `--use-keyring=false`. The CLI also introduced cross-platform support for keyring storage, gained support for GA Task commands, and integrated experimental functionality for the new Agent Socket API.
|
||||
The CLI gained substantial improvements between the two versions. Most notably,
|
||||
beginning in 2.29, Coder’s CLI now stores session tokens in the operating system
|
||||
keyring by default on macOS and Windows, enhancing credential security and
|
||||
reducing exposure from plaintext token storage. Users who rely on directly
|
||||
accessing the token file can opt out using `--use-keyring=false`. The CLI also
|
||||
introduced cross-platform support for keyring storage, gained support for GA
|
||||
Task commands, and integrated experimental functionality for the new Agent
|
||||
Socket API.
|
||||
|
||||
## Changes to be Aware of
|
||||
|
||||
The following are changes introduced after 2.24.X that might break workflows, or require other manual effort to address:
|
||||
The following are changes introduced after 2.24.X that might break workflows, or
|
||||
require other manual effort to address:
|
||||
|
||||
| Initial State (2.24 & before) | New State (2.25–2.29) | Change Required |
|
||||
|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
@@ -57,13 +109,37 @@ The following are changes introduced after 2.24.X that might break workflows, or
|
||||
|
||||
The following are recommendations by the Coder team when performing the upgrade:
|
||||
|
||||
- **Perform the upgrade in a staging environment first:** The cumulative changes between 2.24 and 2.29 introduce new subsystems and lifecycle behaviors, so validating templates, authentication flows, and workspace operations in staging helps avoid production issues
|
||||
- **Audit scripts or tools that rely on the CLI token file:** Since 2.29 uses the OS keyring for session tokens on macOS and Windows, update any tooling that reads the plaintext token file or plan to use `--use-keyring=false`
|
||||
- **Review templates using devcontainers or Terraform:** Explicit agent selection, optional persistent/cached Terraform directories, and updated metadata handling mean template authors should retest builds and startup behavior
|
||||
- **Check and update OIDC provider configuration:** Stricter refresh-token requirements in later releases can cause unexpected logouts or failed CLI authentication if providers are not configured according to updated docs
|
||||
- **Update integrations referencing deprecated API fields:** Code relying on `WorkspaceBuild.task_app_id` must migrate to `Task.WorkspaceAppID`, and any custom integrations built against 2.24 APIs should be validated against the new SDK
|
||||
- **Communicate audit-logging changes to security/compliance teams:** From 2.25 onward, connection events moved into the Connection Log, and older audit entries may be pruned, which can affect SIEM pipelines or compliance workflows
|
||||
- **Validate workspace lifecycle automation:** Since updates now require stopping the workspace first, confirm that automated update jobs, scripts, or scheduled tasks still function correctly in this new model
|
||||
- **Retest agent and task automation built on early experimental features:** Updates to agent readiness, permission checks, and lifecycle ordering may affect workflows developed against 2.24’s looser behaviors
|
||||
- **Monitor workspace, template, and Terraform build performance:** New caching, indexes, and DB optimizations may change build times; observing performance post-upgrade helps catch regressions early
|
||||
- **Prepare user communications around Tasks and UI changes:** Tasks are now GA and more visible in the dashboard, and many UI improvements will be new to users coming from 2.24, so a brief internal announcement can smooth the transition
|
||||
- **Perform the upgrade in a staging environment first:** The cumulative changes
|
||||
between 2.24 and 2.29 introduce new subsystems and lifecycle behaviors, so
|
||||
validating templates, authentication flows, and workspace operations in
|
||||
staging helps avoid production issues
|
||||
- **Audit scripts or tools that rely on the CLI token file:** Since 2.29 uses
|
||||
the OS keyring for session tokens on macOS and Windows, update any tooling
|
||||
that reads the plaintext token file or plan to use `--use-keyring=false`
|
||||
- **Review templates using devcontainers or Terraform:** Explicit agent
|
||||
selection, optional persistent/cached Terraform directories, and updated
|
||||
metadata handling mean template authors should retest builds and startup
|
||||
behavior
|
||||
- **Check and update OIDC provider configuration:** Stricter refresh-token
|
||||
requirements in later releases can cause unexpected logouts or failed CLI
|
||||
authentication if providers are not configured according to updated docs
|
||||
- **Update integrations referencing deprecated API fields:** Code relying on
|
||||
`WorkspaceBuild.task_app_id` must migrate to `Task.WorkspaceAppID`, and any
|
||||
custom integrations built against 2.24 APIs should be validated against the
|
||||
new SDK
|
||||
- **Communicate audit-logging changes to security/compliance teams:** From 2.25
|
||||
onward, connection events moved into the Connection Log, and older audit
|
||||
entries may be pruned, which can affect SIEM pipelines or compliance workflows
|
||||
- **Validate workspace lifecycle automation:** Since updates now require
|
||||
stopping the workspace first, confirm that automated update jobs, scripts, or
|
||||
scheduled tasks still function correctly in this new model
|
||||
- **Retest agent and task automation built on early experimental features:**
|
||||
Updates to agent readiness, permission checks, and lifecycle ordering may
|
||||
affect workflows developed against 2.24’s looser behaviors
|
||||
- **Monitor workspace, template, and Terraform build performance:** New caching,
|
||||
indexes, and DB optimizations may change build times; observing performance
|
||||
post-upgrade helps catch regressions early
|
||||
- **Prepare user communications around Tasks and UI changes:** Tasks are now GA
|
||||
and more visible in the dashboard, and many UI improvements will be new to
|
||||
users coming from 2.24, so a brief internal announcement can smooth the
|
||||
transition
|
||||
|
||||
+5
-5
@@ -995,28 +995,28 @@
|
||||
{
|
||||
"title": "Agent Boundaries",
|
||||
"description": "Understanding Agent Boundaries in Coder Tasks",
|
||||
"path": "./ai-coder/boundary/agent-boundary.md",
|
||||
"path": "./ai-coder/agent-boundaries/index.md",
|
||||
"state": ["premium", "beta"],
|
||||
"children": [
|
||||
{
|
||||
"title": "NS Jail",
|
||||
"description": "Documentation for Namespace Jail",
|
||||
"path": "./ai-coder/boundary/nsjail.md"
|
||||
"path": "./ai-coder/agent-boundaries/nsjail.md"
|
||||
},
|
||||
{
|
||||
"title": "LandJail",
|
||||
"description": "Documentation for LandJail",
|
||||
"path": "./ai-coder/boundary/landjail.md"
|
||||
"path": "./ai-coder/agent-boundaries/landjail.md"
|
||||
},
|
||||
{
|
||||
"title": "Rules Engine",
|
||||
"description": "Documentation for the Boundary rules engine",
|
||||
"path": "./ai-coder/boundary/rules-engine.md"
|
||||
"path": "./ai-coder/agent-boundaries/rules-engine.md"
|
||||
},
|
||||
{
|
||||
"title": "Version Compatibility",
|
||||
"description": "Version requirements and compatibility information",
|
||||
"path": "./ai-coder/boundary/version.md"
|
||||
"path": "./ai-coder/agent-boundaries/version.md"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user