From 4b8c8e4b4e0617727512d5f0b1783bd7690d88b1 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 3 Dec 2025 06:09:02 +0000
Subject: [PATCH] Document custom agent configuration for sandbox.agent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation for the custom command, args, and env fields introduced
in PR #5356 for both AWF and SRT agent sandboxes. These fields allow users
to replace the standard agent installation with custom commands, add
additional arguments, and set environment variables.

Changes:
- Added "Custom AWF Configuration" section with usage example and field reference
- Added "Custom SRT Configuration" section with similar documentation
- Updated "Legacy Format" section to clarify the new 'id' field and its
  precedence over the legacy 'type' field

Related PR: #5356

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/src/content/docs/reference/sandbox.md | 67 ++++++++++++++++++++--
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/docs/src/content/docs/reference/sandbox.md b/docs/src/content/docs/reference/sandbox.md
index b97c771b638..aceb1841372 100644
--- a/docs/src/content/docs/reference/sandbox.md
+++ b/docs/src/content/docs/reference/sandbox.md
@@ -74,6 +74,32 @@ network:
     - "api.example.com"
 ```
 
+#### Custom AWF Configuration
+
+Use custom commands, arguments, and environment variables to replace the standard AWF installation with a custom setup:
+
+```yaml wrap
+sandbox:
+  agent:
+    id: awf
+    command: "docker run --rm my-custom-awf-image"
+    args:
+      - "--custom-logging"
+      - "--debug-mode"
+    env:
+      AWF_CUSTOM_VAR: "custom_value"
+      DEBUG_LEVEL: "verbose"
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Agent identifier: `awf` or `srt` |
+| `command` | `string` | Custom command to replace AWF binary installation |
+| `args` | `string[]` | Additional arguments appended to the command |
+| `env` | `object` | Environment variables set on the execution step |
+
+When `command` is specified, the standard AWF installation is skipped and your custom command is used instead.
+
 ### Sandbox Runtime (SRT)
 
 :::caution[Experimental]
@@ -115,6 +141,31 @@ network:
 Network configuration for SRT is controlled by the top-level `network` field, not the sandbox config. This ensures consistent network policy across all sandbox types.
 :::
 
+#### Custom SRT Configuration
+
+Similar to AWF, SRT supports custom commands, arguments, and environment variables:
+
+```yaml wrap
+features:
+  sandbox-runtime: true
+
+sandbox:
+  agent:
+    id: srt
+    command: "custom-srt-wrapper"
+    args:
+      - "--custom-arg"
+      - "--debug"
+    env:
+      SRT_DEBUG: "true"
+      SRT_CUSTOM_VAR: "test_value"
+    config:
+      filesystem:
+        allowWrite: [".", "/tmp"]
+```
+
+When `command` is specified, the standard SRT installation is skipped. The `config` field can still be used for filesystem configuration.
+
 ## MCP Gateway
 
 The MCP Gateway routes all MCP server calls through a unified HTTP gateway, enabling centralized management, logging, and authentication for MCP tools.
@@ -159,17 +210,25 @@ sandbox:
 
 ## Legacy Format
 
-For backward compatibility, the legacy string format is still supported:
+For backward compatibility, legacy formats are still supported:
 
 ```yaml wrap
-# Legacy format (deprecated)
+# Legacy string format (deprecated)
 sandbox: sandbox-runtime
 
-# Recommended format
+# Legacy object format with 'type' field (deprecated)
 sandbox:
-  agent: srt
+  agent:
+    type: awf
+
+# Recommended format with 'id' field
+sandbox:
+  agent:
+    id: awf
 ```
 
+The `id` field replaces the legacy `type` field in the object format. When both are present, `id` takes precedence.
+
 ## Feature Flags
 
 Some sandbox features require feature flags: