OpenCode SDK

This provider integrates OpenCode, an open-source AI coding agent for the terminal with support for 75+ LLM providers.

Provider IDs

• opencode:sdk - Uses OpenCode's configured model
• opencode - Same as opencode:sdk

The model is configured via the OpenCode CLI or ~/.opencode/config.yaml.

Installation

The OpenCode SDK provider requires both the OpenCode CLI and the SDK package.

1. Install OpenCode CLI

curl -fsSL https://opencode.ai/install | bash

Or via other package managers - see opencode.ai for options.

2. Install SDK Package

npm install @opencode-ai/sdk

:::note

Promptfoo treats the SDK package as an optional runtime dependency, so it only needs to be installed if you want to use the OpenCode SDK provider.

:::

Setup

Configure your LLM provider credentials. For Anthropic:

export ANTHROPIC_API_KEY=your_api_key_here

For OpenAI:

export OPENAI_API_KEY=your_api_key_here

If promptfoo starts the OpenCode server for you, you can also set config.apiKey together with config.provider_id in your provider config.

:::note

If you connect to an existing OpenCode server with baseUrl, that server is responsible for authentication, MCP setup, and custom agents. Promptfoo can still send per-request options like model, tools, format, and workspace, but it cannot reconfigure the remote server.

:::

OpenCode supports 75+ providers - see Supported Providers for the full list.

Quick Start

Basic Usage

Use opencode:sdk to access OpenCode's configured model:

providers:
  - opencode:sdk

prompts:
  - 'Write a Python function that validates email addresses'

Configure your model via the OpenCode CLI: opencode config set model openai/gpt-4o

By default, OpenCode SDK runs in a temporary directory with no tools enabled. When your test cases finish, the temporary directory is deleted.

With Inline Model Configuration

Specify the provider and model directly in your config:

providers:
  - id: opencode:sdk
    config:
      provider_id: anthropic
      model: claude-sonnet-4-20250514

prompts:
  - 'Write a Python function that validates email addresses'

This overrides the model configured via the OpenCode CLI for this specific eval.

With Working Directory

Specify a working directory to enable read-only file tools:

providers:
  - id: opencode:sdk
    config:
      working_dir: ./src

prompts:
  - 'Review the TypeScript files and identify potential bugs'

By default, when you specify a working directory, OpenCode SDK has access to these read-only tools: read, grep, glob, list. Relative working_dir values are resolved from the directory containing the config file.

Structured Output

Use the OpenCode format request option for JSON Schema-constrained responses:

providers:
  - id: opencode:sdk
    config:
      provider_id: openai
      model: gpt-4o-mini
      format:
        type: json_schema
        schema:
          type: object
          additionalProperties: false
          properties:
            summary:
              type: string
            severity:
              type: string
          required:
            - summary
            - severity

prompts:
  - 'Summarize the issue as JSON'

With Workspace

OpenCode workspace support lets you target a specific workspace-aware server context. This requires either working_dir or baseUrl:

providers:
  - id: opencode:sdk
    config:
      working_dir: ./repo
      workspace: feature-branch

prompts:
  - 'Review the files in this workspace'

With Full Tool Access

Enable additional tools for file modifications and shell access:

providers:
  - id: opencode:sdk
    config:
      working_dir: ./project
      tools:
        read: true
        grep: true
        glob: true
        list: true
        write: true
        edit: true
        bash: true
      permission:
        bash: allow
        edit: allow

:::warning

When enabling write/edit/bash tools, consider how you will reset files after each test. See Managing Side Effects.

:::

Supported Parameters

Supported Providers

OpenCode supports 75+ LLM providers through Models.dev:

Cloud Providers:

• Anthropic (Claude)
• OpenAI
• Google AI Studio / Vertex AI
• Amazon Bedrock
• Azure OpenAI
• Groq
• Together AI
• Fireworks AI
• DeepSeek
• Perplexity
• Cohere
• Mistral
• And many more...

Local Models:

• Ollama
• LM Studio
• llama.cpp

Configure your preferred model using the OpenCode CLI:

# Set your default model
opencode config set model anthropic/claude-sonnet-4-20250514

# Or for OpenAI
opencode config set model openai/gpt-4o

# Or for local models
opencode config set model ollama/llama3

Tools and Permissions

Default Tools

With no working_dir specified, OpenCode runs in a temp directory with no tools.

With working_dir specified, these read-only tools are enabled by default:

All Available Tools

* Only enabled when working_dir is specified.

Promptfoo starts with a wildcard deny so tools added by OpenCode, plugins, or MCP servers are not silently enabled. A partial tools object is merged over these defaults. OpenCode groups edit, write, patch, and the upstream apply_patch tool under one edit permission; Promptfoo accepts the documented aliases but rejects conflicting values for that group.

Tool Configuration

Customize available tools:

# Enable additional tools
providers:
  - id: opencode:sdk
    config:
      working_dir: ./project
      tools:
        read: true
        grep: true
        glob: true
        list: true
        write: true # Enable file writing
        edit: true # Enable file editing
        bash: true # Enable shell commands
        patch: true # Enable patch application
        webfetch: true # Enable web fetching
        question: true # Enable user prompts
        skill: true # Enable SKILL.md loading

# Disable specific tools
providers:
  - id: opencode:sdk
    config:
      working_dir: ./project
      tools:
        bash: false # Disable shell

Permissions

Configure tool permissions using simple values or pattern-based rules:

# Simple permissions
providers:
  - id: opencode:sdk
    config:
      permission:
        bash: allow # or 'ask' or 'deny'
        edit: allow
        webfetch: deny
        doom_loop: deny # Prevent infinite agent loops
        external_directory: deny # Block access outside working dir

# Pattern-based permissions
providers:
  - id: opencode:sdk
    config:
      permission:
        bash:
          '*': ask # Catch-all first: OpenCode uses the last matching rule
          'git *': allow # Allow git commands
          'rm *': deny # Deny rm commands
        edit:
          '*.md': allow # Allow editing markdown
          'src/**': ask # Ask for src directory

Additional tools added by future OpenCode releases can be configured using the same shape — unknown keys are forwarded unchanged.

:::note

Promptfoo converts tool defaults and the object form above into the ordered PermissionRuleset array the OpenCode v2 API expects when it creates a session. OpenCode evaluates the last matching rule, so put catch-all patterns before more specific patterns. Explicit permission entries are applied after the tools rules, matching OpenCode's native configuration precedence. An active custom agent's rules are applied last, matching OpenCode's agent-specific override behavior.

OpenCode v1's public prompt API can atomically apply boolean tools, but not permission rules (including simple ask/allow/deny values and patterns). Promptfoo supports v1 permissions only as provider-level configuration on sessions started by Promptfoo. Remote (baseUrl), resumed, and per-prompt v1 policies must use tools; unsupported combinations fail closed.

:::

:::tip Security Recommendation

For security-conscious deployments, set doom_loop: deny and external_directory: deny to prevent infinite agent loops and restrict file access to the working directory.

:::

Skills

OpenCode loads Agent Skills through its native skill tool. Enable the tool for the eval, point working_dir at a repo that contains skills OpenCode can discover, and allow the skill permission if you want a non-interactive run:

providers:
  - id: opencode:sdk
    config:
      working_dir: ./project
      tools:
        skill: true
      permission:
        skill: allow

tests:
  - assert:
      - type: skill-used
        value: review-standards

Promptfoo normalizes OpenCode's native skill tool parts into response.metadata.skillCalls, so skill-used works the same way it does for Claude Agent SDK. Each normalized entry keeps the requested skill name and tool input, records tool failures with is_error: true, and includes the loaded SKILL.md path when OpenCode returns the skill directory in its result metadata. Those errored entries remain available for diagnostics, but they do not count as successful skill-used matches.

Session Management

Ephemeral Sessions (Default)

Creates a new session for each call and deletes it when the call completes:

providers:
  - opencode:sdk

Persistent Sessions

Reuse the same session between calls that use the same provider config:

providers:
  - id: opencode:sdk
    config:
      persist_sessions: true

This reuse is independent of the promptfoo response cache. It is scoped to the lifetime of the provider instance. If you need to continue a session later, capture its sessionId and pass it back with session_id.

Session Resumption

Resume a specific session:

providers:
  - id: opencode:sdk
    config:
      session_id: previous-session-id

OpenCode v2 accepts boolean tools on each prompt and atomically replaces the session's stored permission rules before execution. Promptfoo therefore reapplies its wildcard-deny baseline, read-only defaults, and configured top-level or custom-agent tools when resuming with session_id. Granular permission rules cannot be represented by that prompt contract, so Promptfoo rejects non-empty top-level or custom-agent permission together with session_id on v2. Configure granular rules when creating the session.

OpenCode v1 can atomically replace the tool map on each prompt, so tools remains supported with session_id. Its public SDK cannot atomically apply permission rules on an existing session, so Promptfoo rejects that combination. Create the session through a locally started server when you need pattern-based rules.

:::warning Remote approval state

An existing baseUrl server is a trust boundary. OpenCode keeps in-memory “always allow” approvals, and that server-side state can override configured ask or deny patterns. Use a fresh, isolated server started by Promptfoo when policy isolation is required.

:::

Forked Sessions

Fork a new session off an existing one. The child inherits the parent's compacted history and starts as a fresh conversation. Requires the v2 OpenCode server (silently ignored on v1):

providers:
  - id: opencode:sdk
    config:
      parent_session_id: parent-session-id

parent_session_id is independent of session_id: use session_id to continue the same conversation, or parent_session_id to branch a new one. Setting both is supported, but session_id wins because resumed sessions are not re-forked on create.

Custom Agents

Define custom agents with specific configurations:

providers:
  - id: opencode:sdk
    config:
      custom_agent:
        description: Security-focused code reviewer
        mode: primary # 'primary', 'subagent', or 'all'
        model: claude-sonnet-4-20250514
        temperature: 0.3
        top_p: 0.9 # Nucleus sampling parameter
        steps: 10 # Max iterations before text-only response
        color: '#ff5500' # Visual identification
        tools:
          read: true
          grep: true
          write: false
          bash: false
        permission:
          edit: deny
          external_directory: deny
        prompt: |
          You are a security-focused code reviewer.
          Analyze code for vulnerabilities and report findings.

custom_agent is applied when promptfoo starts the OpenCode server itself. If you use baseUrl, define that agent on the target server and use agent to select it.

MCP Integration

OpenCode supports MCP (Model Context Protocol) servers:

providers:
  - id: opencode:sdk
    config:
      tools:
        'weather-server_*': true # Opt in to the tools needed by this eval
      mcp:
        # Local MCP server
        weather-server:
          type: local
          command: ['node', 'mcp-weather-server.js']
          environment:
            API_KEY: '{{env.WEATHER_API_KEY}}'
          timeout: 30000
          enabled: true

        # Remote MCP server with headers
        api-server:
          type: remote
          url: https://api.example.com/mcp
          headers:
            Authorization: 'Bearer {{env.API_TOKEN}}'

        # Remote MCP server with OAuth
        oauth-server:
          type: remote
          url: https://secure.example.com/mcp
          oauth:
            clientId: '{{env.OAUTH_CLIENT_ID}}'
            clientSecret: '{{env.OAUTH_CLIENT_SECRET}}'
            scope: 'read write'

Like custom_agent, mcp is server configuration. It applies when promptfoo starts the OpenCode server, not when you connect to an already-running server with baseUrl. The wildcard-deny default also applies to MCP and plugin tools. Enabling a server does not grant its tools; opt in with the upstream <server>_<tool> IDs (or a narrow server prefix as shown above).

Caching Behavior

This provider automatically caches responses based on:

• Prompt content
• Working directory fingerprint (if specified)
• Workspace and output format configuration
• Provider and model configuration
• Tool configuration

When MCP servers are configured, caching is disabled by default because MCP tools typically interact with external state. To opt back into caching for deterministic MCP tools, set cache_mcp: true:

providers:
  - id: opencode:sdk
    config:
      cache_mcp: true
      mcp:
        my-server:
          type: local
          command: ['my-deterministic-mcp-server']

MCP configurations containing environment variables, positional command arguments, custom headers, OAuth, URL credentials, or query strings remain uncached so secrets are not included in persistent cache keys. Positional command arguments can contain opaque credentials such as database URLs. Response caching is also disabled for credential-bearing or signed baseUrl values, explicit permission rules, session_id, and persist_sessions. API credentials use a non-secret, process-local cache scope so different provider instances cannot share responses. Repeated calls through one locally started server retain a stable scope without storing or hashing its credentials or environment into the persistent cache key.

To disable caching:

export PROMPTFOO_CACHE_ENABLED=false

To bust the cache for a specific test:

tests:
  - vars: {}
    options:
      bustCache: true

Managing Side Effects

When using tools that allow side effects (write, edit, bash), consider:

• Serial execution: Set evaluateOptions.maxConcurrency: 1 to prevent race conditions
• Git reset: Use git to reset files after each test
• Extension hooks: Use promptfoo hooks for setup/cleanup
• Containers: Run tests in containers for isolation

Example with serial execution:

providers:
  - id: opencode:sdk
    config:
      working_dir: ./project
      tools:
        write: true
        edit: true

evaluateOptions:
  maxConcurrency: 1

Comparison with Other Agentic Providers

Choose based on your use case:

• Multiple providers / local models → OpenCode SDK
• Anthropic-specific features → Claude Agent SDK
• OpenAI-specific features → Codex SDK

Examples

See the examples directory for complete implementations:

• Basic usage - Simple chat-only mode
• Working directory - Read-only local file access
• Structured output - JSON Schema-constrained responses

See Also

• OpenCode Documentation
• OpenCode SDK Reference
• Claude Agent SDK Provider - Alternative agentic provider
• OpenAI Codex SDK Provider - Alternative agentic provider