Execution Targets and Native Runners
Execution targets let a standalone or local gateway invoke local runners or adapter-backed processes instead of a standard upstream HTTP provider.
Connected gateways mark execution targets inactive and do not launch local or self-hosted runners or adapters. Use these targets only where the gateway process owns the execution environment.
Supported families
| Family | Canonical provider value | Support mode |
|---|---|---|
| Browser | browser | adapter only |
| ChatKit | chatkit | adapter only |
| WebSocket | websocket | adapter only |
| Transformers | transformers or transformers:<task>:<model> | native runner or adapter |
| Claude Agent SDK | claude-agent-sdk | native runner or adapter |
| Codex SDK | codex-sdk | native runner or adapter |
| MCP | mcp | native HTTP bridge or adapter |
| OpenAI Agent Runtime | openai-agents | native runner or adapter |
| OpenCode SDK | opencode-sdk | native runner or adapter |
| Bedrock Agents | bedrock-agents | native runner or adapter |
These provider strings are explicitly rejected at config time: manual-input, sequence, simulated-user, slack-feedback, go, ruby, webhook.
Common fields
| Field | Applies to | Notes |
|---|---|---|
provider | all execution targets | Family name or explicit exec: / file:// target |
adapter_command | adapter-backed targets | Required for adapter-only families such as browser, chatkit, and websocket |
adapter_args | adapter-backed targets | Extra argv entries |
working_dir / adapter_cwd | command-based targets | Working directory for the launched process |
execution_timeout_ms | command-based targets | Defaults to 30000 |
cli_env | command-based targets | Literal env map forwarded to the process |
adapter_env | command-based targets | Literal env map; on key conflicts it currently overwrites cli_env |
base_url | mcp native HTTP bridge | Required when not using adapter_command |
path_template | mcp native HTTP bridge | Optional; defaults to /mcp |
cli_envandadapter_envare literal string maps. Config loading does not expand${ENV}placeholders inside them.
Browser example (adapter only)
providers:
targets:
- id: browser-runner
provider: browser
adapter_command: /usr/local/bin/keeptrusts-browser-adapter
adapter_args: [--mode, playwright]
execution_timeout_ms: 45000
working_dir: /srv/browser-runner
cli_env:
LOG_LEVEL: debug
Claude Agent SDK example
providers:
targets:
- id: claude-agent
provider: claude-agent-sdk
model: your-claude-agent-model
working_dir: /srv/agents/claude
additional_directories:
- /srv/shared-prompts
permission_mode: acceptEdits
fallback_model: your-claude-fallback-model
append_allowed_tools: [Read, Write]
disallowed_tools: [Bash]
max_turns: 8
Replace both model placeholders with model identifiers supported by the installed Claude Agent SDK and your provider account.
Codex SDK example
providers:
targets:
- id: codex-agent
provider: codex-sdk
model: your-codex-model
working_dir: /srv/agents/codex
sandbox_mode: workspace-write
approval_policy: on-request
network_access_enabled: false
web_search_enabled: false
skip_git_repo_check: true
Replace your-codex-model with a model currently available to the installed
Codex SDK and account.
MCP example
A plain provider: mcp entry is not enough. The runtime requires either a native bridge base_url or an explicit adapter_command.
providers:
targets:
- id: mcp-http
provider: mcp
base_url: https://mcp.example.com
path_template: /mcp
mcp:
protocol_version: 2026-03-26
session_id: docs-example
tool_validation:
declared_tools: [search]
tool_security:
analysis_mode: local
Transformers example
providers:
targets:
- id: local-transformer
provider: transformers
model: Qwen/Qwen2.5-1.5B-Instruct
adapter_command: /usr/local/bin/keeptrusts-transformers-adapter
adapter_args: [--task, text-generation]
execution_timeout_ms: 60000
adapter_env:
TRANSFORMERS_CACHE: /srv/models
Family-specific extras
The declarative schema accepts these family-specific native-runner fields:
- Claude Agent SDK:
path_to_claude_code_executable,permission_mode,fallback_model,append_allowed_tools,disallowed_tools,allow_all_tools,max_turns - Codex SDK:
codex_path_override,sandbox_mode,approval_policy,network_access_enabled,web_search_enabled,skip_git_repo_check
For Transformers, OpenAI Agents, OpenCode, and Bedrock Agents, use adapter_command, adapter_args, adapter_env, and the common timeout and working-directory fields when you need settings beyond provider and model. aws_region is also accepted for Bedrock-backed targets. Do not add runner-only keys such as device, dtype, or executable override names directly to a declarative provider target; strict config validation rejects them.