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: add BYOK docs, fix tool tables, add platform controls (#24178)

Browse Source 
Fixes several documentation gaps and inaccuracies in the Coder Agents
docs identified during a deep review against the current product state.

## BYOK (User API Keys)

`models.md` stated *"Developers cannot add their own providers, models,
or API keys"* — this has been incorrect since the provider key policy
system shipped (Apr 2, #23751/#23781).

- Added **Key policy** section documenting the three admin toggles
(`central_api_key_enabled`, `allow_user_api_key`,
`allow_central_api_key_fallback`) with a truth table showing all
resolution outcomes
- Added **User API keys (BYOK)** section covering the developer-facing
key management page, status indicators, selection priority, and key
removal
- Updated `platform-controls/index.md` to reference BYOK instead of
claiming keys are admin-only

## Reasoning effort enum fixes

- **OpenAI**: removed `none` — code accepts `minimal, low, medium, high,
xhigh`
- **OpenRouter**: narrowed to `low, medium, high` per
`ReasoningEffortFromChat` in `chatprovider.go`

## Tool table completeness

- Added `spawn_computer_use_agent`, `read_skill`, `read_skill_file` to
`index.md` tool table
- Added "Workspace extension tools" section to `architecture.md` for
`read_skill`/`read_skill_file`
- Fixed orchestration restriction note to list all 5 gated tools instead
of just `spawn_agent`
- Added conditional availability notes for desktop and skills tools

## Platform controls

Three admin-only settings existed in the Behavior tab with no
documentation:

- **Virtual desktop** — admin toggle, Anthropic + portabledesktop
requirements
- **Workspace autostop fallback** — default TTL for agent workspaces
without template-defined autostop
- **Data retention** — moved `chat-retention.md` into
`platform-controls/` since it's admin-only, fixed nav path

---

> PR generated with Coder Agents
This commit is contained in:
Matt Vollmer
2026-04-08 18:24:12 -04:00
committed by GitHub
parent 461a31e5d8
commit 506fba9ebf
6 changed files with 181 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai-coder/agents/architecture.md
+9
View File
@@ -180,6 +180,15 @@ configuration set by an administrator.
|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `web_search` | Searches the internet for up-to-date information. Available when web search is enabled for the configured Anthropic, OpenAI, or Google provider. |
### Workspace extension tools
These tools are conditionally available based on the workspace contents.
| Tool | What it does |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------|
| `read_skill` | Reads the instructions for a workspace skill by name. Available when the workspace has skills discovered in `.agents/skills/`. |
| `read_skill_file` | Reads a supporting file from a skill's directory. |
## What runs where
Understanding the split between the control plane and the workspace is central
docs/ai-coder/agents/index.md
+31 -23
View File
@@ -232,35 +232,43 @@ model. Developers select from enabled models when starting a chat.
The agent has access to a set of workspace tools that it uses to accomplish
tasks:
| Tool | Description |
|--------------------|---------------------------------------------------------|
| `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 |
| `propose_plan` | Present a Markdown plan file for user review |
| `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 |
| `execute` | Run shell commands in the workspace |
| `process_output` | Retrieve output from a background process |
| `process_list` | List all tracked processes in the workspace |
| `process_signal` | Send a signal (terminate/kill) to a tracked process |
| `spawn_agent` | Delegate a task to a sub-agent running in parallel |
| `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) |
| Tool | Description |
|----------------------------|--------------------------------------------------------------------------|
| `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 |
| `propose_plan` | Present a Markdown plan file for user review |
| `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 |
| `execute` | Run shell commands in the workspace |
| `process_output` | Retrieve output from a background process |
| `process_list` | List all tracked processes in the workspace |
| `process_signal` | Send a signal (terminate/kill) to a tracked process |
| `spawn_agent` | Delegate a task to a sub-agent running in parallel |
| `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 |
| `spawn_computer_use_agent` | Spawn a sub-agent with desktop interaction (screenshot, mouse, keyboard) |
| `read_skill` | Read the instructions for a workspace skill by name |
| `read_skill_file` | Read a supporting file from a skill's directory |
| `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`, `propose_plan`) 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.
`start_workspace`, `propose_plan`) and orchestration tools (`spawn_agent`,
`wait_agent`, `message_agent`, `close_agent`, `spawn_computer_use_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.
`spawn_computer_use_agent` additionally requires an Anthropic provider and
the virtual desktop feature to be enabled by an administrator.
`read_skill` and `read_skill_file` are available when the workspace contains
skills in its `.agents/skills/` directory.
## Comparison to Coder Tasks
docs/ai-coder/agents/models.md
+87 -13
View File
@@ -1,10 +1,13 @@
# Models
Administrators configure LLM providers and models from the Coder dashboard.
These are deployment-wide settings — developers do not manage API keys or
provider configuration. They select from the set of models that an administrator
Providers, models, and API keys are deployment-wide settings managed by
platform teams. Developers select from the set of models that an administrator
has enabled.
Optionally, administrators can allow developers to supply their own API keys
for specific providers. See [User API keys](#user-api-keys-byok) below.
## Providers
Each LLM provider has a type, an API key, and an optional base URL override.
@@ -57,6 +60,38 @@ access to LLM providers. See
[Architecture](./architecture.md#no-api-keys-in-workspaces) for details
on this security model.
### Key policy
Each provider has three policy flags that control how API keys are sourced:
| Setting | Default | Description |
|-------------------------|---------|-----------------------------------------------------------------------------------------------------|
| Central API key | On | The provider uses a deployment-managed API key entered by an administrator. |
| Allow user API keys | Off | Developers may supply their own API key for this provider. |
| Central key as fallback | Off | When user keys are allowed, fall back to the central key if a developer has not set a personal key. |
At least one credential source must be enabled. These settings appear in the
provider configuration form under **Key policy**.
The interaction between these flags determines whether a provider is available
to a given developer:
| Central key | User keys allowed | Fallback | Developer has key | Result |
|-------------|-------------------|----------|-------------------|----------------------|
| On | Off | — | — | Uses central key |
| Off | On | — | Yes | Uses developer's key |
| Off | On | — | No | Unavailable |
| On | On | Off | Yes | Uses developer's key |
| On | On | Off | No | Unavailable |
| On | On | On | Yes | Uses developer's key |
| On | On | On | No | Uses central key |
When a developer's personal key is present, it always takes precedence over
the central key. When user keys are required and fallback is disabled,
the provider is unavailable to developers who have not saved a personal key —
even if a central key exists. This is intentional: it enforces that each
developer authenticates with their own credentials.
## Models
Each model belongs to a provider and has its own configuration for context limits,
@@ -132,11 +167,11 @@ fields appear dynamically in the admin UI when you select a provider.
#### OpenAI
| Option | Description |
|-----------------------|---------------------------------------------------------------------------------------------------|
| Reasoning Effort | How much effort the model spends reasoning (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). |
| Max Completion Tokens | Cap on completion tokens for reasoning models. |
| Parallel Tool Calls | Whether the model can call multiple tools at once. |
| Option | Description |
|-----------------------|-------------------------------------------------------------------------------------------|
| Reasoning Effort | How much effort the model spends reasoning (`minimal`, `low`, `medium`, `high`, `xhigh`). |
| Max Completion Tokens | Cap on completion tokens for reasoning models. |
| Parallel Tool Calls | Whether the model can call multiple tools at once. |
#### Google
@@ -147,10 +182,10 @@ fields appear dynamically in the admin UI when you select a provider.
#### OpenRouter
| Option | Description |
|-------------------|-------------------------------------------------------------------------------|
| Reasoning Enabled | Enable extended reasoning mode. |
| Reasoning Effort | Reasoning effort level (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). |
| Option | Description |
|-------------------|---------------------------------------------------|
| Reasoning Enabled | Enable extended reasoning mode. |
| Reasoning Effort | Reasoning effort level (`low`, `medium`, `high`). |
#### Vercel AI Gateway
@@ -176,10 +211,49 @@ The model selector uses the following precedence to pre-select a model:
1. **Admin-designated default** — the model marked with the star icon.
1. **First available model** — if no default is set and no history exists.
Developers cannot add their own providers, models, or API keys. If no models
are configured, the chat interface displays a message directing developers to
Developers cannot add their own providers or models. If no models are
configured, the chat interface displays a message directing developers to
contact an administrator.
## User API keys (BYOK)
When an administrator enables **Allow user API keys** on a provider,
developers can supply their own API key from the Agents settings page.
### Managing personal API keys
1. Navigate to the **Agents** page in the Coder dashboard.
1. Open **Settings** and select the **API Keys** tab.
1. Each provider that allows user keys is listed with a status indicator:
- **Key saved** — your personal key is active and will be used for requests.
- **Using shared key** — no personal key set, but the central deployment
key is available as a fallback.
- **No key** — you must add a personal key before you can use this provider.
1. Enter your API key and click **Save**.
Personal API keys are encrypted at rest using the same database encryption
as deployment-managed keys. The dashboard never displays a saved key — only
whether one is set.
### How key selection works
When you start a chat, the control plane resolves which API key to use for
each provider:
1. If you have a personal key for the provider, it is used.
1. If you do not have a personal key and central key fallback is enabled,
the deployment-managed key is used.
1. If you do not have a personal key and fallback is disabled, the provider
is unavailable to you. Models from that provider will not appear in the
model selector.
### Removing a personal key
Click **Remove** on the provider card in the API Keys settings tab. If
central key fallback is enabled, subsequent requests will use the shared
deployment key. If fallback is disabled, the provider becomes unavailable
until you add a new personal key.
## Using an LLM proxy
Organizations that route LLM traffic through a centralized proxy — such as
docs/ai-coder/agents/chat-retention.md → docs/ai-coder/agents/platform-controls/chat-retention.md
+2 -7
View File
@@ -17,8 +17,8 @@ deleted. Both operations run in batches of 1,000 rows per cycle.
## Configuration
Navigate to **Deployment Settings** > **Agents** > **Behavior** to configure
the conversation retention period. The default is 30 days. Use the toggle to
Navigate to the **Agents** page, open **Settings**, and select the **Behavior**
tab to configure the conversation retention period. The default is 30 days. Use the toggle to
disable retention entirely.
The retention period is stored as the `agents_chat_retention_days` key in the
@@ -37,8 +37,3 @@ The retention period is stored as the `agents_chat_retention_days` key in the
If a user unarchives a conversation whose files were purged, stale file
references are automatically cleaned up by FK cascades. The conversation
remains usable but previously attached files are no longer available.
## Related links
- [Coder Agents](./index.md)
- [Data Retention](../../admin/setup/data-retention.md)
docs/ai-coder/agents/platform-controls/index.md
+46 -8
View File
@@ -11,11 +11,12 @@ This means:
- **All agent configuration is admin-level.** Providers, models, system prompts,
and tool permissions are set by platform teams from the control plane. These
are not user preferences — they are deployment-wide policies.
- **Developers never need to configure anything.** A developer just describes
the work they want done. They do not need to pick a provider, enter an API
key, or write a system prompt — the platform team has already set all of
that up. The goal is not to restrict developers, but to make configuration
unnecessary for a great experience.
- **Developers never need to configure anything by default.** A developer just
describes the work they want done. They do not need to pick a provider or
write a system prompt — the platform team has already set all of that up.
When a platform team enables user API keys for a provider, developers may
optionally supply their own key — but this is an opt-in policy decision, not
a requirement.
- **Enforcement, not defaults.** Settings configured by administrators are
enforced server-side. Developers cannot override them. This is a deliberate
distinction — a setting that a user can change is a preference, not a policy.
@@ -36,8 +37,12 @@ self-hosted models), and per-model parameters like context limits, thinking
budgets, and reasoning effort.
Developers select from the set of models an administrator has enabled. They
cannot add their own providers, supply their own API keys, or access models that
have not been explicitly configured.
cannot add their own providers or access models that have not been explicitly
configured.
When an administrator enables user API keys on a provider, developers can
supply their own key from the Agents settings page. See
[User API keys (BYOK)](../models.md#user-api-keys-byok) for details.
See [Models](../models.md) for setup instructions.
@@ -84,6 +89,30 @@ opt-out, or opt-in for each chat.
See [MCP Servers](./mcp-servers.md) for configuration details.
### Virtual desktop
Administrators can enable a virtual desktop within agent workspaces.
When enabled, agents can use `spawn_computer_use_agent` to interact with a
desktop environment using screenshots, mouse, and keyboard input.
This setting is available under **Agents** > **Settings** > **Behavior**.
It requires:
- The [portabledesktop](https://registry.coder.com/modules/coder/portabledesktop)
module to be installed in the workspace template.
- An Anthropic provider to be configured (computer use is an Anthropic
capability).
### Workspace autostop fallback
Administrators can set a default autostop timer for agent-created workspaces
that do not define one in their template. Template-defined autostop rules always
take precedence. Active conversations extend the stop time automatically.
This setting is available under **Agents** > **Settings** > **Behavior**.
The maximum configurable value is 30 days. When disabled, workspaces follow
their template's autostop rules (or none, if the template does not define any).
### Usage limits and analytics
Administrators can set spend limits to cap LLM usage per user within a rolling
@@ -93,10 +122,19 @@ breakdowns.
See [Usage & Analytics](./usage-insights.md) for details.
### Data retention
Administrators can configure a retention period for archived conversations.
When enabled, archived conversations and orphaned files older than the
retention period are automatically purged. The default is 30 days.
This setting is available under **Agents** > **Settings** > **Behavior**.
See [Data Retention](./chat-retention.md) for details.
## Where we are headed
The controls above cover providers, models, system prompts, templates, MCP
servers, and usage limits. We are continuing to invest in platform controls
servers, usage limits, and data retention. We are continuing to invest in platform controls
based on what we hear from customers deploying agents in regulated and
enterprise environments.
docs/manifest.json
+6 -6
View File
@@ -1250,6 +1250,12 @@
"description": "Spend limits and cost tracking for Coder Agents",
"path": "./ai-coder/agents/platform-controls/usage-insights.md",
"state": ["early access"]
},
{
"title": "Data Retention",
"description": "Automatic cleanup of old conversation data",
"path": "./ai-coder/agents/platform-controls/chat-retention.md",
"state": ["early access"]
}
]
},
@@ -1264,12 +1270,6 @@
"description": "Programmatic access to Coder Agents via the experimental Chats API",
"path": "./ai-coder/agents/chats-api.md",
"state": ["early access"]
},
{
"title": "Chat Data Retention",
"description": "Automatic cleanup of old chat data",
"path": "./ai-coder/agents/chat-retention.md",
"state": ["early access"]
}
]
}