---
sidebar_position: 42
title: OpenCode SDK
description: 'Use OpenCode SDK for evals with 75+ providers, built-in tools, and terminal-native AI agent'
---

# OpenCode SDK

This provider integrates [OpenCode](https://opencode.ai/), 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`

When you omit `provider_id` and `model`, OpenCode selects the model using its own configuration and defaults. Set a global model in `~/.config/opencode/opencode.json`; see [OpenCode configuration](https://opencode.ai/docs/config/). Additional suffixes on the promptfoo provider ID identify provider instances; they do not select a model.

## Installation

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

### 1. Install OpenCode CLI

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

Or via other package managers - see [opencode.ai](https://opencode.ai) for options.

### 2. Install SDK Package

```bash
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:

```bash
export ANTHROPIC_API_KEY=your_api_key_here
```

For OpenAI:

```bash
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.

For servers started by promptfoo, setting `OPENCODE_SERVER_PASSWORD` in the server environment also authenticates the SDK client with that password. Set `OPENCODE_SERVER_USERNAME` to customize the username, which defaults to `opencode`. These variables can come from an env file or provider `env` overrides. See [OpenCode server authentication](https://opencode.ai/docs/server/#authentication).

:::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](#supported-providers) for the full list.

## Quick Start

### Basic Usage

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

```yaml title="promptfooconfig.yaml"
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
providers:
  - opencode:sdk

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

Select a model with `/models` in OpenCode, or set `model` in your OpenCode configuration.

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

Set `provider_id` to the OpenCode provider key and `model` to the model ID within that provider:

```yaml title="promptfooconfig.yaml"
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
providers:
  - id: opencode:sdk
    config:
      provider_id: anthropic
      model: claude-sonnet-5

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

This overrides OpenCode's model selection for this specific eval. Keep `provider_id` separate from `model`; for example, a custom provider with a model ID of `team/model-name` uses `provider_id: my-provider` and `model: team/model-name`.

### With Working Directory

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

```yaml
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
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.

For isolated workspaces (`copy_working_dir`), unset repository-selecting Git environment variables such as `GIT_DIR`, `GIT_WORK_TREE`, and `GIT_INDEX_FILE` before starting promptfoo. OpenCode's local server inherits these variables directly, so isolated calls reject them.

### Structured Output

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

```yaml title="promptfooconfig.yaml"
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
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`:

```yaml
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
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:

```yaml
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](#managing-side-effects).

:::

## Supported Parameters

| Parameter                 | Type              | Description                                                                | Default                                |
| ------------------------- | ----------------- | -------------------------------------------------------------------------- | -------------------------------------- |
| `apiKey`                  | string            | Inject API key into a spawned OpenCode server for `provider_id`            | Environment variable                   |
| `baseUrl`                 | string            | URL for an existing OpenCode server                                        | Auto-start server                      |
| `hostname`                | string            | Server hostname when starting a new server                                 | `127.0.0.1`                            |
| `port`                    | number            | Server port when starting a new server                                     | Auto-select                            |
| `timeout`                 | number            | Server startup timeout in milliseconds                                     | `30000`                                |
| `log_level`               | string            | OpenCode server log level (`debug`, `info`, `warn`, `error`, `off`)        | Provider default                       |
| `working_dir`             | string            | Directory for file operations and read-only default tools                  | Temporary directory                    |
| `copy_working_dir`        | boolean \| string | Fresh copy of `working_dir` per eval step ([details][isolated-workspaces]) | false                                  |
| `workspace`               | string            | Workspace identifier for workspace-aware OpenCode requests                 | None                                   |
| `provider_id`             | string            | LLM provider (`anthropic`, `openai`, `google`, `ollama`, etc.)             | OpenCode default                       |
| `model`                   | string            | Model ID within `provider_id`; set both for an explicit selection          | OpenCode default                       |
| `format`                  | object            | Output format, including JSON Schema structured output                     | Text                                   |
| `variant`                 | string            | Provider/model variant defined in OpenCode config                          | Default variant                        |
| `tools`                   | object            | Tool configuration                                                         | None; read-only with `working_dir`     |
| `permission`              | object            | Permission configuration for tools                                         | No extra rules; wildcard-deny baseline |
| `agent`                   | string            | Built-in or preconfigured agent to use                                     | Default agent                          |
| `custom_agent`            | object            | Custom agent configuration when promptfoo starts the OpenCode server       | None                                   |
| `session_id`              | string            | Resume an existing session                                                 | Create new session                     |
| `parent_session_id`       | string            | Fork from an existing session (v2 server only); inherits compacted history | None                                   |
| `persist_sessions`        | boolean           | Reuse the same session for repeated calls with the same provider config    | `false`                                |
| `mcp`                     | object            | MCP server configuration when promptfoo starts the OpenCode server         | None                                   |
| `cache_mcp`               | boolean           | Enable caching when MCP is configured                                      | `false`                                |
| `restart_server_per_call` | boolean           | Restart the owned server when the request traceparent changes              | `false`                                |

## Supported Providers

OpenCode supports 75+ LLM providers through [Models.dev](https://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 default model in OpenCode's global configuration:

```json title="~/.config/opencode/opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5"
}
```

OpenCode's `model` setting uses the full `provider/model-id` format, such as `openai/gpt-4o` or `ollama/llama3`. Use the provider key and model ID configured on your OpenCode server, including any model path segments.

## 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:

| Tool   | Purpose                         |
| ------ | ------------------------------- |
| `read` | Read file contents              |
| `grep` | Search file contents with regex |
| `glob` | Find files by pattern           |
| `list` | List directory contents         |

### All Available Tools

| Tool        | Purpose                                  | Default |
| ----------- | ---------------------------------------- | ------- |
| `bash`      | Execute shell commands                   | false   |
| `edit`      | Modify existing files                    | false   |
| `write`     | Create/overwrite files                   | false   |
| `read`      | Read file contents                       | true\*  |
| `grep`      | Search file contents with regex          | true\*  |
| `glob`      | Find files by pattern                    | true\*  |
| `list`      | List directory contents                  | true\*  |
| `patch`     | Apply diff patches                       | false   |
| `todowrite` | Create task lists                        | false   |
| `todoread`  | Read task lists                          | false   |
| `webfetch`  | Fetch web content                        | false   |
| `question`  | Prompt user for input during execution   | false   |
| `skill`     | Load SKILL.md files into conversation    | false   |
| `lsp`       | Code intelligence queries (experimental) | false   |

\* 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:

```yaml
# 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:

```yaml
# 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
```

| Permission           | Purpose                          |
| -------------------- | -------------------------------- |
| `bash`               | Shell command execution          |
| `edit`               | File editing                     |
| `read`               | Reading files                    |
| `glob`               | Finding files by pattern         |
| `grep`               | Searching file contents          |
| `list`               | Listing directories              |
| `task`               | Subtask execution                |
| `lsp`                | Code intelligence queries        |
| `skill`              | Loading SKILL.md files           |
| `webfetch`           | Web fetching                     |
| `websearch`          | Web search                       |
| `codesearch`         | Codebase search                  |
| `todowrite`          | Writing to todo list             |
| `question`           | Interactive user prompts         |
| `doom_loop`          | Prevents infinite agent loops    |
| `external_directory` | Access outside working 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:

```yaml
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`](/docs/configuration/expected-outputs/deterministic/#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.

Because OpenCode is multi-turn, the `skill` tool is usually invoked before the
final response, so its tool part is absent from that response. To catch those
calls, promptfoo fetches the session message history after each prompt and
collects the parts between the user message that triggered the prompt and the
assistant message it returned. This costs one extra `session.messages` call per
prompt and is skipped whenever the `skill` tool is disabled — which includes the
default `tools` config — so evals that never opt into skills pay nothing. If
either boundary message is missing from the returned history (a truncated or
paginated response, for example), promptfoo falls back to the final message's
parts rather than risk attributing another prompt's skill calls to this one.

## Session Management

### Ephemeral Sessions (Default)

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

```yaml
providers:
  - opencode:sdk
```

### Persistent Sessions

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

```yaml
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:

```yaml
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):

```yaml
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:

```yaml
providers:
  - id: opencode:sdk
    config:
      custom_agent:
        description: Security-focused code reviewer
        mode: primary # 'primary', 'subagent', or 'all'
        model: anthropic/claude-sonnet-5
        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.

`custom_agent.model` uses OpenCode's full [`provider/model-id` format](https://opencode.ai/docs/agents/#model). For example, `anthropic/claude-sonnet-5` selects the Anthropic provider. Unlike the top-level `model` field, it includes the provider key; promptfoo passes this string unchanged. Omit it to use OpenCode's agent model defaults.

| Parameter     | Type    | Description                               |
| ------------- | ------- | ----------------------------------------- |
| `description` | string  | Required. Explains the agent's purpose    |
| `mode`        | string  | 'primary', 'subagent', or 'all'           |
| `model`       | string  | Full OpenCode `provider/model-id`         |
| `temperature` | number  | Response randomness (0.0-1.0)             |
| `top_p`       | number  | Nucleus sampling (0.0-1.0)                |
| `steps`       | number  | Max iterations before text-only response  |
| `color`       | string  | Hex color for visual identification       |
| `tools`       | object  | Tool configuration                        |
| `permission`  | object  | Permission configuration                  |
| `prompt`      | string  | Custom system prompt                      |
| `disable`     | boolean | Disable this agent                        |
| `hidden`      | boolean | Hide from @ autocomplete (subagents only) |

## MCP Integration

OpenCode supports MCP (Model Context Protocol) servers:

```yaml
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`:

```yaml
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`, `persist_sessions`, and `restart_server_per_call`. 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:

```bash
export PROMPTFOO_CACHE_ENABLED=false
```

To bust the cache for a specific test:

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

## Trace Correlation (`trajectory:*` assertions)

For an OpenCode tracing plugin that reads `OPENCODE_TRACEPARENT` at startup, enable
`restart_server_per_call` to pass each request's trace context to the server:

```yaml
tracing:
  enabled: true

providers:
  - id: opencode:sdk
    config:
      restart_server_per_call: true
```

Configure the plugin separately to export spans to promptfoo's OTLP receiver. This option
passes trace context; it does not install a plugin or create OpenCode spans.

Set this option on the provider; prompt-level overrides are rejected. The provider restarts
its server when the traceparent changes, serializes calls on that provider instance, and
disables response caching. Calls with the same traceparent reuse
the server. A missing or invalid traceparent clears the server's inherited trace context
and produces a warning once.

This option cannot be combined with `baseUrl`, `persist_sessions`, `session_id`, or
`parent_session_id`: the provider must own the server and be free to discard its sessions.
Omit `port` or set it to `0` so each replacement can start before the old process exits.
With the option off, the provider seeds `OPENCODE_TRACEPARENT` when it starts a server,
unless the environment already supplies a value.

## Managing Side Effects

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

- **Isolated workspaces**: Set `copy_working_dir: true` to run each eval step in a fresh copy of `working_dir` (see [isolated workspaces][isolated-workspaces])
- **Serial execution**: Set `evaluateOptions.maxConcurrency: 1` to prevent race conditions

[isolated-workspaces]: /docs/guides/evaluate-coding-agents#isolated-workspaces

- **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:

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

evaluateOptions:
  maxConcurrency: 1
```

## Comparison with Other Agentic Providers

| Feature               | OpenCode SDK      | Claude Agent SDK | Codex SDK    |
| --------------------- | ----------------- | ---------------- | ------------ |
| Provider flexibility  | 75+ providers     | Anthropic only   | OpenAI only  |
| Architecture          | Client-server     | Direct API       | Thread-based |
| Local models          | Ollama, LM Studio | No               | No           |
| Tool ecosystem        | Native + MCP      | Native + MCP     | Native       |
| Working dir isolation | Yes               | Yes              | Git required |

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](https://github.com/promptfoo/promptfoo/tree/main/examples/provider-opencode-sdk) for complete implementations:

- [Basic usage](https://github.com/promptfoo/promptfoo/tree/main/examples/provider-opencode-sdk/basic) - Simple chat-only mode
- [Working directory](https://github.com/promptfoo/promptfoo/tree/main/examples/provider-opencode-sdk/working-dir) - Read-only local file access
- [Structured output](https://github.com/promptfoo/promptfoo/tree/main/examples/provider-opencode-sdk/structured-output) - JSON Schema-constrained responses

## See Also

- [OpenCode Documentation](https://opencode.ai/docs/)
- [OpenCode SDK Reference](https://opencode.ai/docs/sdk/)
- [Claude Agent SDK Provider](/docs/providers/claude-agent-sdk/) - Alternative agentic provider
- [OpenAI Codex SDK Provider](/docs/providers/openai-codex-sdk/) - Alternative agentic provider