Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Tool

Stability: beta -- This resource kind ships with orloj.dev/v1 and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.

spec

  • type (string): tool type. Allowed values: http, external, grpc, webhook-callback, mcp, wasm, cli. Unknown values are rejected at apply time.
  • endpoint (string): tool endpoint URL (or host:port for gRPC).
  • description (string): human-readable description of the tool. Passed to model gateways for richer tool definitions. Auto-populated for MCP-generated tools.
  • input_schema (object): JSON Schema for tool parameters. Passed to model gateways for structured parameter definitions. Auto-populated for MCP-generated tools.
  • mcp_server_ref (string): name of the McpServer that provides this tool. Required when type=mcp.
  • mcp_tool_name (string): the tool name as reported by the MCP server's tools/list. Required when type=mcp.
  • cli (object): CLI tool configuration. Required when type=cli.
    • command (string): binary path or name to execute. Required.
    • args ([]string): argument templates. Each entry is evaluated as a Go text/template with the parsed JSON input as data context. Each template produces one argv entry.
    • image (string): container image containing the binary. Required when isolation_mode is not none.
    • image_pull_secret (string): name of a Secret containing registry credentials for pulling cli.image. The Secret must contain either a .dockerconfigjson key with a complete Docker config JSON, or registry, username, and password keys. Requires image to be set.
    • network (string): Docker network mode for the container. Defaults to bridge (unlike HTTP tools which default to none). Set to none for tools that do not need network access.
    • stdin_from_input (bool): if true, pipe the raw model input to the process's stdin.
    • output (string): which streams to return. Allowed values: stdout (default), stderr, both.
    • working_dir (string): working directory inside the container or on the host.
    • env (map[string]string): literal environment variables.
    • env_from ([]object): environment variables resolved from secrets.
      • name (string): env var name. Required.
      • secretRef (string): Orloj secret reference. Required.
      • key (string): key within the secret (default: value).
  • capabilities ([]string): declared operations.
  • operation_classes ([]string): operation class annotations. Allowed values: read, write, delete, admin. Used by ToolPermission.operation_rules for per-class policy verdicts.
  • risk_level (string): low, medium, high, critical.
  • runtime (object):
    • timeout (duration string)
    • isolation_mode: none, sandboxed, container, kubernetes, wasm
    • retry.max_attempts (int)
    • retry.backoff (duration string)
    • retry.max_backoff (duration string)
    • retry.jitter: none, full, equal
  • auth (object):
    • profile (string): auth profile. Allowed values: bearer, api_key_header, basic, oauth2_client_credentials. Defaults to bearer when secretRef is set.
    • secretRef (string): namespaced secret reference. Required when profile is set.
    • headerName (string): custom header name. Required when profile=api_key_header.
    • tokenURL (string): OAuth2 token endpoint. Required when profile=oauth2_client_credentials.
    • scopes ([]string): OAuth2 scopes.

Defaults and Validation

  • type defaults to http. Unknown types are rejected with a validation error. mcp type tools are typically auto-generated by the McpServer controller; see Connect an MCP Server. cli type tools invoke local binaries via execve; see CLI Tool Guide.
  • cli.command is required when type=cli. cli.image is required when isolation_mode is not none. cli.image_pull_secret requires cli.image.
  • cli.output defaults to stdout. cli.network defaults to bridge.
  • auth is not supported for type=cli tools. Use cli.env_from for credential injection.
  • auth.profile defaults to bearer when secretRef is set. Unknown profiles are rejected.
  • auth.headerName is required when profile=api_key_header.
  • auth.tokenURL is required when profile=oauth2_client_credentials.
  • capabilities are trimmed and deduplicated (case-insensitive).
  • operation_classes are trimmed, lowercased, and deduplicated. Invalid values are rejected. Defaults to ["read"] for low/medium risk, ["write"] for high/critical risk.
  • risk_level defaults to low.
  • runtime.timeout defaults to 30s and must parse as duration.
  • runtime.isolation_mode defaults to:
    • container for type=cli (regardless of risk level)
    • sandboxed for high/critical risk (non-CLI)
    • none for low/medium risk (non-CLI)
    • kubernetes must be set explicitly; requires --tool-k8s-enabled=true
  • runtime.retry defaults:
    • max_attempts -> 1
    • backoff -> 0s
    • max_backoff -> 30s
    • jitter -> none

status

  • phase, lastError, observedGeneration

Examples:

  • examples/resources/tools/*.yaml
  • examples/resources/tools/wasm-reference/wasm_echo_tool.yaml
  • examples/resources/tools/cli_kubectl_tool.yaml
  • examples/resources/tools/cli_gh_tool.yaml

See also: Tool concepts.