opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify agent permission inheritance and default security posture (#23194)

Browse Source 
Addresses five documentation gaps identified from an internal agents
briefing Q&A, specifically around what permissions an agent inherits
from the user:

1. **No privilege escalation** — Added explicit statement that the agent
has the exact same permissions as the user. No escalation, no shared
service account.
2. **Cross-user workspace isolation** — Added statement that agents
cannot access workspaces belonging to other users.
3. **Default-state warning** — Added WARNING callouts that agent
workspaces inherit the user's full network access unless templates
explicitly restrict it.
4. **Tool boundary statement** — Added explicit statement that the agent
cannot act outside its defined tool set and has no direct access to the
Coder API.
5. **Template visibility scoped to user RBAC** — Clarified that template
selection respects the user's role and permissions.

Changes across 3 files:
- `docs/ai-coder/agents/index.md`
- `docs/ai-coder/agents/architecture.md`
- `docs/ai-coder/agents/platform-controls/template-optimization.md`

---
PR generated with Coder Agents
This commit is contained in:
Matt Vollmer
2026-03-18 12:15:50 +00:00
committed by GitHub
parent d42008e93d
commit 481c132135
3 changed files with 78 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai-coder/agents/architecture.md
+40 -6
View File
@@ -106,6 +106,11 @@ Tools are how the agent takes action. Each tool call from the LLM translates to
a concrete operation — either inside a workspace or within the control plane
itself.
The agent is restricted to the tool set defined in this section. It has no
direct access to the Coder API beyond what these tools expose and cannot
execute arbitrary operations against the control plane. If a capability is
not represented by a tool, the agent cannot perform it.
### Workspace connection lifecycle
The connection to a workspace is **lazy**. It is not established when a chat
@@ -135,13 +140,16 @@ They traverse the same Tailnet tunnel used by web terminals and IDE connections.
### Platform tools
These tools run entirely within the control plane. They do not require a
workspace connection.
workspace connection. Platform and orchestration tools are only available to
root chats — sub-agents spawned by `spawn_agent` do not have access to them
and cannot create workspaces or spawn further sub-agents.
| Tool | What it does |
|--------------------|-------------------------------------------------------------------|
| `list_templates` | Browses available workspace templates, sorted by popularity. |
| `read_template` | Gets template details and configurable parameters. |
| `create_workspace` | Creates a workspace from a template and waits for it to be ready. |
| Tool | What it does |
|--------------------|----------------------------------------------------------------------------------------|
| `list_templates` | Browses available workspace templates, sorted by popularity. |
| `read_template` | Gets template details and configurable parameters. |
| `create_workspace` | Creates a workspace from a template and waits for it to be ready. |
| `start_workspace` | Starts the chat's workspace if it is currently stopped. Idempotent if already running. |
### Orchestration tools
@@ -155,6 +163,16 @@ parallel.
| `message_agent` | Sends a follow-up message to a running sub-agent. |
| `close_agent` | Stops a running sub-agent. |
### Provider tools
These tools are executed server-side by the LLM provider, not by the control
plane or workspace. They are conditionally available based on the model
configuration set by an administrator.
| Tool | What it does |
|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `web_search` | Searches the internet for up-to-date information. Available when web search is enabled for the configured Anthropic, OpenAI, or Google provider. |
## What runs where
Understanding the split between the control plane and the workspace is central
@@ -244,6 +262,22 @@ anonymous identity. If a developer submits a prompt that results in a pull
request, that pull request is attributed to them via the git authentication
already configured in your Coder deployment.
### Permission boundaries
The agent operates with the exact same permissions as the user who submitted
the prompt. If a user cannot access a template, workspace, or API endpoint
through the Coder dashboard or CLI, the agent cannot access it either. There
is no privilege escalation.
This extends to workspace isolation: the agent can only interact with
workspaces owned by the user who started the chat. It cannot read files,
execute commands, or connect to workspaces belonging to other users.
Template visibility follows the same rule. When the agent lists available
templates, it sees only the templates the user is authorized to access.
The agent cannot provision a workspace from a template the user does not
have permission to use.
## Scaling and resource impact
The control plane overhead for Coder Agents is minimal. The heavy computation
docs/ai-coder/agents/index.md
+30 -2
View File
@@ -83,9 +83,9 @@ This means:
- **Lower infrastructure cost** — workspaces are only created when the agent
needs to do real development work.
When a workspace _is_ needed, the agent reads the available templates —
When a workspace _is_ needed, the agent reads the templates available to that user —
including their descriptions and parameters — selects the appropriate one, and
creates a workspace automatically. Users can also manually choose which workspace is used when starting a new chat.
creates a workspace automatically. Template visibility is scoped to the user's role and permissions, so the agent can only select templates the user is authorized to use. Users can also manually choose which workspace is used when starting a new chat.
Platform teams control template routing by writing clear template descriptions.
For example, a description like "Use this template for Python backend services
@@ -174,6 +174,16 @@ entirely:
- **User identity is always attached.** Every action the agent takes — PRs
opened, code pushed, commands run — is tied to the user who submitted the
prompt. There is no shared bot identity or anonymous execution.
- **No privilege escalation.** The agent operates with the exact same
permissions as the user who submitted the prompt. If a developer cannot
access a template, workspace, or resource through the Coder dashboard,
the agent cannot access it either. There is no escalation of privileges
and no shared service account.
- **Workspace isolation is preserved.** The agent can only access workspaces
owned by the user who submitted the prompt. There is no cross-user
workspace access — an agent running on behalf of one developer cannot
read files, execute commands, or interact with another developer's
workspaces.
> [!TIP]
> For highly sensitive environments, create a dedicated set of templates for
@@ -181,6 +191,16 @@ entirely:
> templates. Because the AI comes from the control plane, these templates don't
> need any outbound access to LLM providers.
<!-- break between callouts -->
> [!WARNING]
> By default, agent workspaces have the same network access and permissions
> as any workspace the user creates manually. If your templates do not
> restrict outbound network access, the agent has full internet access from
> the workspace. See [Template Optimization](./platform-controls/template-optimization.md)
> for guidance on configuring network boundaries and scoping credentials for
> agent workloads.
## LLM provider support
Coder Agents works with any LLM provider. Administrators configure providers
@@ -217,6 +237,7 @@ tasks:
| `list_templates` | Browse available workspace templates |
| `read_template` | Get template details and configurable parameters |
| `create_workspace` | Create a workspace from a template |
| `start_workspace` | Start a stopped workspace for the current chat |
| `read_file` | Read file contents from the workspace |
| `write_file` | Write a file to the workspace |
| `edit_files` | Perform search-and-replace edits across files |
@@ -225,11 +246,18 @@ tasks:
| `wait_agent` | Wait for a sub-agent to complete and collect its result |
| `message_agent` | Send a follow-up message to a running sub-agent |
| `close_agent` | Stop a running sub-agent |
| `web_search` | Search the internet (provider-native, when enabled) |
These tools connect to the workspace over the same secure connection used for
web terminals and IDE access. No additional ports or services are required in
the workspace.
Platform tools (`list_templates`, `read_template`, `create_workspace`,
`start_workspace`) and orchestration tools (`spawn_agent`)
are only available to root chats. Sub-agents do
not have access to these tools and cannot create workspaces or spawn further
sub-agents.
## Comparison to Coder Tasks
Coder Agents is a new approach that differs from
docs/ai-coder/agents/platform-controls/template-optimization.md
+8
View File
@@ -112,6 +112,14 @@ for more detail on the security model.
## Scope permissions and credentials
> [!WARNING]
> By default, agent workspaces inherit the same network access and
> permissions as any workspace the user creates manually. If your templates
> do not explicitly restrict outbound network access, the agent has full
> internet access from the workspace. Review the guidance below and in
> [Configure network boundaries](#configure-network-boundaries) to lock
> down agent workloads appropriately.
The agent operates with the same identity and permissions as the user who
submitted the prompt. There is no privilege escalation — if a developer cannot
access a resource through the Coder dashboard, the agent cannot access it