@@ -8,7 +8,7 @@ Field-by-field refusals are in [Hosted agents](hosted-agents.md). This page is t
 
 ## Install a CLI
 
-Neither CLI is installed by default. Installing both into the base image makes the image large.
+Install one CLI. Installing both into the base image makes the image large. When the request does not name an adapter, the server uses the first in the product order: `codex`. Name Qwen Code in the request, or set `EBX_AGENTS_DEFAULT=qwen-code`, to use the other one.
 
 ```bash
 npm install -g @openai/codex          # binary name: codex
@@ -38,12 +38,23 @@ python examples/agents/complete_case.py
 
 The shapes below are what the server returns. The server assigns the session id.
 
-A model id such as `gpt-5` does not select a CLI:
+When the request does not name an adapter, the server uses the first in the product order (`codex`). A model id such as `gpt-5` is passed to that CLI. It does not switch the adapter:
 
 ```text
-POST /v1/agents/sessions  400
+POST /v1/agents/sessions  {"agent":{"model":"gpt-5"}}  200
+agent.id: codex
+agent.model: gpt-5
 X-Easy-Sandbox-Local: 1
-code: agents.adapter_required
+```
+
+`GET /v1/agents/runtimes` uses the same paging as the other lists, so the default `order` is `desc`. Pass `order=asc` to see the product order `codex`, then `qwen-code`. `default: true` marks the runtime used when the request does not name one. The flag does not follow the array index. With no config it is on `codex`. After `EBX_AGENTS_DEFAULT=qwen-code` it moves to `qwen-code`.
+
+Name the other one:
+
+```text
+POST /v1/agents/sessions  {"adapter":"qwen-code","agent":{"model":"gpt-5"}}  200
+agent.id: qwen-code
+agent.model: gpt-5
 ```
 
 An adapter name that is not supported today, for example `claude-code`:
 
@@ -28,6 +28,51 @@ The Agents routes stay off until the process is started with `EBX_SERVER_ENABLED
 
 Codex and Qwen Code are supported today. Checklist, the local header, and the 404s: [Hosted agents — Best practices](hosted-agents.md#best-practices).
 
+## One agent by default
+
+Install only the CLI you are going to call. Installing both Codex and Qwen Code makes the image large.
+
+The server's order is `codex`, then `qwen-code`. A request that does not name an adapter uses the first. `GET /v1/agents/runtimes?order=asc` returns them in that order. The list's default `order` is `desc`. `default: true` marks the one in effect. It does not follow the array index.
+
+```bash
+npm install -g @openai/codex
+```
+
+To use Qwen Code, send `adapter`, `runtime`, or the `X-EBX-Adapter` header, or set `model` to `qwen-code` (aliases `qwen` and `qwencode`). A model id such as `gpt-5` is passed to the selected CLI. It does not switch the adapter.
+
+Move the default off the first entry:
+
+```bash
+export EBX_AGENTS_DEFAULT=qwen-code
+```
+
+A JSON file named by `EBX_AGENTS_CONFIG` does the same with a top-level `default` or `agents.default`. `claude-code`, Cursor, and Qoder stay 404.
+
+## Open Agents routes one endpoint at a time
+
+`groups.agents: true` is only the gate for this group. Each Agents route has its own endpoint id, the same way `upload` and `shell` do. The default scope is `agents:use`. This opens session create and nothing else:
+
+```python
+from easy_sandbox.server import SandboxServer, ServerPolicy, default_table
+
+policy = ServerPolicy.only("agents_sessions_create").with_options(groups={"agents": True})
+server = SandboxServer(route_table=default_table(), policy=policy)
+```
+
+The same policy in YAML:
+
+```yaml
+groups:
+  agents: true
+endpoints:
+  "*":
+    enabled: false
+  agents_sessions_create:
+    enabled: true
+```
+
+These endpoints do not accept `paths` or specialised `params`. A policy that sets either fails to load. The full endpoint id list is in [Fine-grained capabilities](fine-grained-capabilities.md).
+
 ## Secrets are not echoed
 
 `GET /env` omits a variable whose name contains `TOKEN`, `SECRET`, `KEY`, `PASSWORD`, or `CREDENTIAL`. When a policy is loaded it also omits `EBX_SERVER_TOKEN`, `EBX_SERVER_POLICY`, `EBX_SERVER_POLICY_FILE`, every `token_env` name, and every name that starts with `EBX_SERVER_`.
 
@@ -18,6 +18,8 @@ The template server listens on **port 9000**. Point an OpenAI-shaped client at `
 * Codex and Qwen Code are supported today. A body that names an adapter that is not supported yet is HTTP 404 `not_found_error` with `x-should-retry: false`.
 * Treat every response as local. Read the header `X-Easy-Sandbox-Local: 1` (errors included). `x_easy_sandbox.compute` is `local_process`, `local_state`, or `none`.
 * Do not call `POST /v1/responses/input_tokens`. It is 404 `agents.not_implemented_locally` with `x-should-retry: false`. No tokenizer matches the model the CLI will call.
+* Install one CLI in the image. A request that does not name an adapter uses the first in the product order (`codex`). Name `adapter`, `runtime`, or `X-EBX-Adapter`, or set `EBX_AGENTS_DEFAULT`, to use another.
+* Open endpoints one id at a time. `groups.agents: true` is only the gate. Each route's default scope is `agents:use`. See [Fine-grained capabilities](fine-grained-capabilities.md).
 * Leave the group off until a session needs it. Start the process with `EBX_SERVER_ENABLED_GROUPS=agents`.
 * Keep model API keys out of the HTTP client. The server token, when set, is the only credential these examples send.
 
@@ -62,8 +64,9 @@ Selection order:
 1. `X-EBX-Adapter` header, or a body field `adapter` / `runtime` (top-level or under `agent`)
 2. `agent.model` or `model` when that string is one of the names above (a real model id such as `gpt-5-codex` is passed through to the CLI and does not choose an adapter)
 3. Config `agents.default`: the `EBX_AGENTS_DEFAULT` environment variable, or in `EBX_AGENTS_CONFIG` a JSON string at `default` or `agents.default`
+4. Otherwise the first runtime in the product order: `codex`, then `qwen-code`
 
-If none of those names an adapter, the response is **400** `agents.adapter_required`.
+`GET /v1/agents/runtimes` defaults to `order=desc`. `order=asc` is the product order above. `default: true` marks the runtime step 4 selected. It does not follow the array index. A real model id (`gpt-5`) is passed to that CLI and does not change the adapter. Name the other runtime in the request to use it.
 
 ## Sessions, events, items, turns
 
@@ -97,7 +100,7 @@ curl -s -D - -o /dev/null -X POST \
 
 `GET .../items`, `GET .../turns`, `GET .../turns/{turn_id}`, and `GET .../turns/{turn_id}/items` return the list envelope `{object, data, first_id, last_id, has_more}`. `limit` is 1–100 (default 20) and `order` is `asc` or `desc` (default `desc`).
 
-`GET /v1/agents/runtimes` lists **codex** and **qwen-code** only, including whether each binary is on `PATH`.
+`GET /v1/agents/runtimes` lists **codex** and **qwen-code** only, including whether each binary is on `PATH`. Each object has `default`. That flag is true for the runtime used when the request does not name one. `order=asc` is `codex`, then `qwen-code`. The default `order` is `desc`.
 
 ## Agent definitions
 
 
@@ -569,7 +569,7 @@ All of these need Playwright. If `import playwright` fails the handler returns `
 
 ### `agents` (off until enabled)
 
-Turn the group on with `EBX_SERVER_ENABLED_GROUPS=agents` (or `default_table().enable_group(CapabilityGroup.AGENTS)` before `serve()`). This slice hosts the Codex CLI (`codex`) and Qwen Code (`qwen-code`, also `qwen` and `qwencode`). Any other adapter name is `404` `not_found_error` with `x-should-retry: false`. If the body and `agents.default` (`EBX_AGENTS_DEFAULT`) name neither adapter, create calls are `400` `agents.adapter_required`.
+Turn the group on with `EBX_SERVER_ENABLED_GROUPS=agents` (or `default_table().enable_group(CapabilityGroup.AGENTS)` before `serve()`). Codex CLI (`codex`) and Qwen Code (`qwen-code`, also `qwen` and `qwencode`) are supported today. An adapter name that is not supported yet is `404` `not_found_error` with `x-should-retry: false`. When the body and `agents.default` (`EBX_AGENTS_DEFAULT`) do not name an adapter, create calls use the first in the product order: `codex`. Each Agents route can be enabled on its own. Endpoint ids are in [Fine-grained capabilities](fine-grained-capabilities.md). The default scope is `agents:use`.
 
 Every route here is a local operation. Every response carries `X-Easy-Sandbox-Local: 1` and every object an `x_easy_sandbox` label (`local`, `compute`, `differences`). A field the server cannot honor is `400` with `param`, never accepted and ignored. Objects belong to the caller; a foreign id answers like an unknown id.
 
@@ -597,7 +597,7 @@ Every route here is a local operation. Every response carries `X-Easy-Sandbox-Lo
 
 No local capability, `404` `not_found_error` (`agents.not_implemented_locally`, `x-should-retry: false`): `POST /v1/responses/input_tokens`, `DELETE /v1/models/{id}`, and executor registration and channel.
 
-The CLIs are not installed until a session uses them. See [Hosted agents](hosted-agents.md) for every refusal, environment variable and difference code. Best practices (Codex and Qwen only, the local header, 404 for Claude, Cursor, and Qoder, and 404 for `input_tokens`) are in [Hosted agents — Best practices](hosted-agents.md#best-practices).
+The CLIs are not installed until a session uses them. See [Hosted agents](hosted-agents.md) for every refusal, environment variable and difference code. Supported adapters, the local header, and the 404s for names that are not supported yet and for `input_tokens` are in [Hosted agents — Best practices](hosted-agents.md#best-practices).
 
 ---
 
 
@@ -8,7 +8,7 @@
 
 ## 安装 CLI
 
-默认不装。两个都装进基础镜像会把镜像做大。
+默认只装一个。两个都装进基础镜像会把镜像做大。没在请求里点名时，服务端用产品顺序里的第一个：`codex`。要用 Qwen Code，在请求里写出来，或用 `EBX_AGENTS_DEFAULT=qwen-code` 把默认换成它。
 
 ```bash
 npm install -g @openai/codex          # 二进制名 codex
@@ -38,12 +38,23 @@ python examples/agents/complete_case.py
 
 下面是响应形状。会话 id 由服务端生成。
 
-未给出适配器名，模型 id `gpt-5` 不会用来选 CLI：
+未给出适配器名时，用顺序里的第一个（`codex`）。模型 id `gpt-5` 传给这个 CLI，不用来换适配器：
 
 ```text
-POST /v1/agents/sessions  400
+POST /v1/agents/sessions  {"agent":{"model":"gpt-5"}}  200
+agent.id: codex
+agent.model: gpt-5
 X-Easy-Sandbox-Local: 1
-code: agents.adapter_required
+```
+
+`GET /v1/agents/runtimes` 和其他列表一样，默认 `order=desc`。加上 `order=asc` 才是产品顺序 `codex`、`qwen-code`。`default: true` 标出没点名时会用的那一个，不看它在数组里的位置。没有配置时标在 `codex` 上。`EBX_AGENTS_DEFAULT=qwen-code` 之后改到 `qwen-code`。
+
+要点名另一个：
+
+```text
+POST /v1/agents/sessions  {"adapter":"qwen-code","agent":{"model":"gpt-5"}}  200
+agent.id: qwen-code
+agent.model: gpt-5
 ```
 
 目前未支持的适配器名称，例如 `claude-code`：
 
@@ -28,6 +28,51 @@ Agents 路由保持关闭，直到进程以 `EBX_SERVER_ENABLED_GROUPS=agents`
 
 目前支持 Codex 和 Qwen Code。检查清单、本地响应头和 404 见[托管代理 — 最佳实践](hosted-agents.md#最佳实践)。
 
+## 默认一个 agent
+
+镜像里只安装要调用的那一个 CLI。Codex 和 Qwen Code 都装进去会把镜像做大。
+
+服务端的顺序是 `codex`，然后 `qwen-code`。请求没有点名适配器时，用第一个。`GET /v1/agents/runtimes?order=asc` 按这个顺序返回。列表默认的 `order` 是 `desc`。`default: true` 标出当前默认，不看数组下标。
+
+```bash
+npm install -g @openai/codex
+```
+
+要用 Qwen Code，在请求里写 `adapter`、`runtime` 或请求头 `X-EBX-Adapter`，或把 `model` 写成 `qwen-code`（别名 `qwen`、`qwencode`）。`gpt-5` 这种模型 id 会传给被选中的 CLI，不会用来换适配器。
+
+把默认从第一个换成另一个：
+
+```bash
+export EBX_AGENTS_DEFAULT=qwen-code
+```
+
+`EBX_AGENTS_CONFIG` 指向的 JSON 里，顶层 `default` 或 `agents.default` 作用相同。`claude-code`、Cursor、Qoder 仍然是 404。
+
+## 按接口打开 Agents 路由
+
+`groups.agents: true` 只是这组路由的门。和 `upload`、`shell` 一样，每个 Agents 路由有自己的端点 id，默认 scope 是 `agents:use`。只打开创建会话：
+
+```python
+from easy_sandbox.server import SandboxServer, ServerPolicy, default_table
+
+policy = ServerPolicy.only("agents_sessions_create").with_options(groups={"agents": True})
+server = SandboxServer(route_table=default_table(), policy=policy)
+```
+
+同一份策略写成 YAML：
+
+```yaml
+groups:
+  agents: true
+endpoints:
+  "*":
+    enabled: false
+  agents_sessions_create:
+    enabled: true
+```
+
+这些端点不接受 `paths` 和专用 `params`。写上会在加载策略时失败。完整端点 id 见[细粒度能力](fine-grained-capabilities.md)。
+
 ## 密钥不会被回显
 
 `GET /env` 会略过名称里含有 `TOKEN`、`SECRET`、`KEY`、`PASSWORD` 或 `CREDENTIAL` 的变量。加载了策略时，还会略过 `EBX_SERVER_TOKEN`、`EBX_SERVER_POLICY`、`EBX_SERVER_POLICY_FILE`、每一个 `token_env` 名称，以及每一个以 `EBX_SERVER_` 开头的名称。