Execution Targets and Runners

An execution target is a provider target that runs a local process, such as the Claude Agent SDK, the Codex SDK, or an adapter program, instead of calling an HTTP provider. The gateway applies your policy chain to the request and then hands it to that process.

Execution targets work only on a standalone or local gateway that controls its execution environment. A connected gateway does not start local runners or adapters. For your first request, use the quickstart with an HTTP provider.

Before you configure a runner

• Install the SDK or executable on the gateway host, authenticate it, and run a small task with it directly, as the same operating system user as the gateway.
• The YAML does not install a runtime, create a working directory, or give the host a provider subscription.
• Adapter programs such as verdictan-browser-adapter and verdictan-transformers-adapter in the examples are programs that you supply. The CLI does not install them. The gateway starts the adapter, writes the request to its standard input, and reads its standard output.

Syntax

provider selects the execution family. An adapter-only family needs adapter_command. A family with a native runner can run without an adapter and takes its own fields.

Inside policy-config.yaml

providers:
  targets:
    - id: <target-id>
      provider: <family>
      model: <model>
      adapter_command: /usr/local/bin/<adapter>
      adapter_args: [<arg>]
      execution_timeout_ms: 30000

Family	provider value	Mode
Browser	browser	Adapter only
ChatKit	chatkit or openai:chatkit	Adapter only
WebSocket	websocket	Adapter only
Transformers	transformers or transformers:<task>:<model>	Native runner or adapter
Claude Agent SDK	claude-agent-sdk or anthropic:claude-agent-sdk	Native runner or adapter
Codex SDK	codex-sdk or openai:codex-sdk	Native runner or adapter
MCP	mcp	Native HTTP bridge or adapter
OpenAI Agents	openai-agents or openai:agents	Native runner or adapter
OpenCode SDK	opencode-sdk	Native runner or adapter
Bedrock Agents	bedrock-agents	Native runner or adapter

provider: anthropic or provider: openai alone is an HTTP provider, not an execution target. Lint rejects the unsupported families manual-input, sequence, simulated-user, slack-feedback, go, ruby, and webhook.

Fields

Shared fields

Field	Type	Default	Description
provider	string		Family name, or an exec: or file:// target. Required.
adapter_command	string		Adapter program. Required for adapter-only families.
adapter_args	array of strings		Arguments for adapter_command
adapter_cwd	string	working_dir	Working directory of the adapter
working_dir	string		Working directory of native runners and adapters
execution_timeout_ms	integer	30000	Timeout of the local process
cli_env	map of strings		Environment variables for the process
adapter_env	map of strings		Environment variables for the process. Overrides the same key in cli_env.
base_url	string		MCP bridge endpoint. Required for mcp without adapter_command.
path_template	string	/mcp	Path on the MCP bridge endpoint

cli_env and adapter_env are literal values. The gateway does not expand ${VAR} placeholders in them.

Claude Agent SDK fields

Field	Type	Description
path_to_claude_code_executable	string	Path of the Claude executable for native runs
permission_mode	string	For example default, plan, acceptEdits, bypassPermissions, or dontAsk
fallback_model	string	Model to use when the primary model fails
append_allowed_tools	array of strings	Tools added to the default allow list
disallowed_tools	array of strings	Tools that the runtime blocks
allow_all_tools	boolean	Allows every available tool
max_turns	integer	Maximum turns in one run
additional_directories	array of strings	More directories that the runtime can access

Codex SDK fields

Field	Type	Description
codex_path_override	string	Path of the Codex executable for native runs
sandbox_mode	string	For example read-only, workspace-write, or danger-full-access
approval_policy	string	For example never, on-request, on-failure, or untrusted
network_access_enabled	boolean	Allows outbound network access
web_search_enabled	boolean	Allows web search
skip_git_repo_check	boolean	Skips the Git repository check

MCP bridge fields

With provider: mcp and a base_url, the mcp object configures the native HTTP bridge:

Field	Type	Description
mcp.protocol_version	string	MCP protocol version sent to the server
mcp.session_id	string	Fixed session ID
mcp.tool_validation	object	Same fields as the tool-validation control
mcp.tool_security	object	Same fields as the tool-security control
mcp.tool_budget	object	Same fields as the tool-budget control

Transformers, OpenAI Agents, OpenCode, and Bedrock Agents use only the shared fields besides provider and model. Bedrock Agents also accepts aws_region.

Examples

Browser adapter

Inside policy-config.yaml

providers:
  targets:
    - id: browser-runner
      provider: browser
      adapter_command: /usr/local/bin/verdictan-browser-adapter
      adapter_args: [--mode, playwright]
      execution_timeout_ms: 45000
      working_dir: /srv/browser-runner
      cli_env:
        LOG_LEVEL: debug

Claude Agent SDK native runner

A read-only setup: plan mode, the Read tool allowed, and shell and write tools blocked.

Inside policy-config.yaml

providers:
  targets:
    - id: claude-agent
      provider: anthropic:claude-agent-sdk
      model: your-claude-agent-model
      working_dir: /srv/agents/claude
      additional_directories:
        - /srv/shared-prompts
      permission_mode: plan
      fallback_model: your-claude-fallback-model
      append_allowed_tools: [Read]
      disallowed_tools: [Bash, Write, Edit]
      max_turns: 8

Use models that the installed SDK and your account support.

Codex SDK native runner

Inside policy-config.yaml

providers:
  targets:
    - id: codex-agent
      provider: codex-sdk
      model: your-codex-model
      working_dir: /srv/agents/codex
      sandbox_mode: read-only
      approval_policy: on-request
      network_access_enabled: false
      web_search_enabled: false
      skip_git_repo_check: false

MCP native HTTP bridge

Inside policy-config.yaml

providers:
  targets:
    - id: mcp-http
      provider: mcp
      base_url: https://mcp.example.com
      path_template: /mcp
      mcp:
        tool_validation:
          declared_tools: [search]
        tool_security:
          analysis_mode: local

Transformers adapter

Inside policy-config.yaml

providers:
  targets:
    - id: local-transformer
      provider: transformers
      model: Qwen/Qwen2.5-1.5B-Instruct
      adapter_command: /usr/local/bin/verdictan-transformers-adapter
      adapter_args: [--task, text-generation]
      execution_timeout_ms: 60000
      adapter_env:
        TRANSFORMERS_CACHE: /srv/models

Verify the runner

1. Lint the full configuration and start the standalone or local gateway with it.
2. Send one short request to the target. Examine the returned text, and the gateway logs for the runner that ran.
3. Make sure that the working directory and permissions stay inside your approved boundary. Keep read-only settings unless a workflow needs writes.

HTTP 501 with unsupported_execution_target means that the process did not start. Examine the family, the installed dependencies, the executable path, and the gateway mode before you change the prompt.

Limits and failure behavior

• Lint rejects an adapter-only family without adapter_command, or with path_to_claude_code_executable or codex_path_override.
• Lint rejects codex_path_override on a Claude Agent SDK target and path_to_claude_code_executable on a Codex SDK target.
• Lint rejects provider: mcp without base_url, url, or adapter_command.
• exec: targets accept only allowed programs, such as python, node, npx, deno, bun, and cargo. Programs such as rm and curl are rejected.
• Provider targets reject unknown keys. Use only the fields on this page.

Next steps

• Environment Variable Use: give credentials and paths to the gateway process.
• Tool Validation: check tool declarations in the request.
• Gateway MCP Surface: use the gateway itself as an MCP server.