Execution Targets and Native Runners

Beyond standard HTTP providers, Keeptrusts supports execution targets — local processes, native CLI runners, and adapter-backed providers that run tools, agents, and MCP bridges directly from the gateway.

Use this page when

• You need the exact command, config, API, or integration details for Execution Targets and Native Runners.
• You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
• If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Overview

Execution targets let you proxy requests to:

• Claude Agent SDK — Run Claude Code as a native agent
• Codex SDK — Run OpenAI Codex as a sandboxed agent
• MCP bridges — Connect to Model Context Protocol servers
• Browser agents — Playwright-based browser automation
• Custom adapters — Any executable that speaks the adapter protocol

Adapter families

Family	String value	Support	Provider aliases
Claude Agent SDK	claude-agent-sdk	Native or adapter	claude-agent-sdk, claude-code, anthropic:claude-agent-sdk
Codex SDK	codex-sdk	Native or adapter	codex-sdk, codex, openai:codex-sdk, openai:codex
OpenAI Agents	openai-agents	Native or adapter	openai-agents, openai:agents
OpenCode SDK	opencode-sdk	Native or adapter	opencode-sdk, opencode, openai:opencode-sdk
Bedrock Agents	bedrock-agents	Native or adapter	bedrock-agents, bedrock:agents, aws:agents
MCP	mcp	Native or adapter	mcp
Browser	browser	Adapter only	browser, browser-agent, playwright-browser
ChatKit	chatkit	Adapter only	chatkit, openai:chatkit:*
WebSocket	websocket	Adapter only	websocket
Transformers	transformers	Native or adapter	transformers, transformers.js, transformers:*

Native families have a default executable and can run without adapter_command. Adapter only families require an adapter_command.

Common adapter fields

These fields apply to all execution targets:

pack:
  name: config-execution-targets-providers-1
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: my-agent
    provider: claude-agent-sdk
    model: claude-sonnet-4-20250514
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Field	Type	Default	Description
adapter_command	string	—	Path to the adapter executable
adapter_args	string[]	[]	Arguments passed to the adapter
adapter_cwd	string	—	Working directory for the adapter process (falls back to working_dir)
adapter_env	map	{}	Environment variables injected into the adapter process
execution_timeout_ms	integer	30000	Timeout for the execution target (ms, min: 1)
working_dir	string	—	Working directory for native runners (fallback for adapter_cwd)
additional_directories	string[]	[]	Extra directories exposed to the runner
cli_env	map	{}	Environment variables for native runners (merged with adapter_env, takes precedence)

Claude Agent SDK

Run Claude Code as a native agent with tool permissions, turn limits, and fallback models.

Minimal config

pack:
  name: config-execution-targets-providers-2
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: claude-agent
    provider: claude-agent-sdk
    model: claude-sonnet-4-20250514
    secret_key_ref:
      env: ANTHROPIC_API_KEY
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Full config

pack:
  name: config-execution-targets-providers-3
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: claude-agent
    provider: claude-agent-sdk
    model: claude-sonnet-4-20250514
    secret_key_ref:
      env: ANTHROPIC_API_KEY
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Claude Agent SDK fields

Field	Type	Default	Description
path_to_claude_code_executable	string	"claude"	Path to the Claude executable
permission_mode	string	—	Tool permission level (see below)
append_allowed_tools	string[]	[]	Tools added to the default allow-list
disallowed_tools	string[]	[]	Tools explicitly blocked
allow_all_tools	boolean	false	Permit all available tools
fallback_model	string	—	Model to use when the primary fails
max_turns	integer	—	Maximum conversation turns per invocation (min: 1)

Permission modes

Mode	Behavior
default	Standard tool permissions (ask for approval)
plan	Plan-only mode — suggest tool calls but don't execute
acceptEdits	Auto-accept file edits
bypassPermissions	Skip all permission checks
dontAsk	Never prompt for approval, silently deny

bypassPermissions disables all safety prompts. Use only in sandboxed environments with trusted inputs.

Codex SDK

Run OpenAI Codex as a sandboxed agent with network and approval controls.

Minimal config

pack:
  name: config-execution-targets-providers-4
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: codex-agent
    provider: codex-sdk
    model: codex-mini
    secret_key_ref:
      env: OPENAI_API_KEY
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Full config

pack:
  name: config-execution-targets-providers-5
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: codex-agent
    provider: codex-sdk
    model: codex-mini
    secret_key_ref:
      env: OPENAI_API_KEY
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Codex SDK fields

Field	Type	Default	Description
codex_path_override	string	"codex"	Path to the Codex executable
sandbox_mode	string	—	Sandbox restriction level
approval_policy	string	—	When to require human approval
network_access_enabled	boolean	—	Allow outbound network access
web_search_enabled	boolean	—	Allow web search
skip_git_repo_check	boolean	—	Skip Git repository safety check

Sandbox modes

Mode	Behavior
read-only	Can read files but not write
workspace-write	Can write within the working directory
danger-full-access	Full filesystem access (use with caution)

Approval policies

Policy	Behavior
never	Never ask for approval
on-request	Ask before every action
on-failure	Ask only when an action fails
untrusted	Ask for all untrusted tool calls

MCP bridge

Connect to Model Context Protocol servers with tool validation and security policies.

Minimal config

pack:
  name: config-execution-targets-providers-6
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: mcp-server
    provider: mcp
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Full config with validation

pack:
  name: config-execution-targets-providers-7
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: mcp-server
    provider: mcp
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

MCP bridge fields

Field	Type	Default	Description
mcp.protocol_version	string	"2026-03-26"	MCP protocol version
mcp.session_id	string	—	Operator-defined session identifier
mcp.tool_validation	object	—	Tool allowlist and schema validation
mcp.tool_security	object	—	Argument-level security checks

Tool validation

Field	Type	Default	Description
declared_tools	string[]	[]	Allowlisted tool names
schemas	map	{}	JSON Schema per tool (keys = tool names)
allow_undeclared	boolean	false	Allow unlisted tools (logged but not blocked)
semantic_validation.enabled	boolean	false	Enable LLM-based semantic validation
semantic_validation.endpoint	string	—	OpenAI-compatible validation endpoint
semantic_validation.model	string	—	Model for semantic validation
semantic_validation.secret_key_ref	string	—	Env var with validation API key
semantic_validation.timeout_ms	integer	3000	Timeout for validation call (min: 1)

Tool security

Field	Type	Default	Description
analysis_mode	string	"local"	local (static analysis) or external (firewall)
firewall_endpoint	string	—	External firewall URL (required when external)
secret_key_ref	object	—	Environment-backed secret reference for the firewall API key
fail_closed	boolean	true	Block if firewall unavailable
blocked_entity_types	string[]	[]	Entity types that trigger local blocks

Default blocked entity types: pan, ssn, jwt, aws_access_key, mrn, private_key.

Browser agents

Run Playwright-based browser automation agents.

pack:
  name: config-execution-targets-providers-8
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: browser-agent
    provider: browser
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Browser targets always require adapter_command — there is no native default executable.

Custom adapters

Any executable that speaks the adapter protocol can be used as a provider:

pack:
  name: config-execution-targets-providers-9
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: custom-agent
    provider: openai-agents
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Combining with policy chains

Execution targets work with the same policy chain as HTTP providers:

pack:
  name: agent-gateway
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: claude-agent
    provider: claude-agent-sdk
    model: claude-sonnet-4-20250514
    secret_key_ref:
      env: ANTHROPIC_API_KEY
policies:
  chain:
  - agent-firewall
  - prompt-injection
  - audit-logger
policy:
  agent-firewall:
    allowed_tools:
    - Read
    - Write
    - Bash
    blocked_tools:
    - WebFetch
    max_actions_per_session: 100

For AI systems

• Canonical terms: Keeptrusts, policy-config.yaml, execution targets, adapter_command, adapter_args, adapter_cwd, adapter_env, cli_env, execution_timeout_ms, claude-agent-sdk, codex-sdk, openai-agents, mcp, browser, permission_mode, sandbox_mode.
• Adapter families: Claude Agent SDK, Codex SDK, OpenAI Agents, OpenCode SDK, Bedrock Agents, MCP, Browser, ChatKit, WebSocket, Transformers.
• Best next pages: Providers Configuration, Cloud Provider Configuration, Agent Firewall policy.

For engineers

• "Native" families (Claude, Codex, MCP) have default executables and work without adapter_command; "adapter only" families (Browser, ChatKit, WebSocket) require it.
• Set execution_timeout_ms appropriately for long-running agent tasks (120s+ for complex code generation or multi-turn agents).
• cli_env takes precedence over adapter_env when both set the same variable.
• Use permission_mode: "plan" for Claude agents in production to prevent unreviewed tool execution.
• MCP tool_validation.allow_undeclared: false ensures only declared tools can be called; undeclared tools are blocked.
• Combine execution targets with agent-firewall policy for tool-level access control.

For leaders

• Execution targets extend the gateway to proxy requests to native agent SDKs (Claude Code, Codex, MCP servers) with the same policy enforcement as HTTP providers.
• Permission modes and sandbox restrictions provide security boundaries for agent code execution without custom infrastructure.
• MCP tool validation and security ensure agents can only call declared tools with validated arguments, preventing unauthorized actions.
• All execution targets work with the same policy chain (prompt-injection, agent-firewall, audit-logger), providing consistent governance regardless of provider type.

Next steps

• Providers Configuration — HTTP provider targets and routing
• Cloud Provider Configuration — Azure, AWS, GCP-specific fields
• Agent Firewall policy — tool-level access control for agents
• Security and Network Configuration — network-level controls