OpenCode Zen

Use OpenCode Zen models with Docker Agent.

Overview

OpenCode Zen is a curated gateway of tested and verified AI models provided by the OpenCode team. It offers pay-per-use access to a wide range of models — from GPT and Claude to open-source models — all through a single API key. Several free models are also available.

Docker Agent includes built-in support for OpenCode Zen as an alias provider for OpenAI-compatible models. Anthropic and Google models are supported via custom provider definitions.

Setup

1. Sign in to OpenCode Zen, add billing information, and copy your API key

2. Set the environment variable:

   export OPENCODE_API_KEY=your-api-key
   

3. Verify available models:

   curl https://opencode.ai/zen/v1/models
   

Usage

Inline Syntax

The simplest way to use OpenCode Zen with a free model:

agents:
  root:
    model: opencode-zen/deepseek-v4-flash-free
    description: Assistant using OpenCode Zen (free)
    instruction: You are a helpful assistant.

Named Model

For more control over parameters:

models:
  zen_model:
    provider: opencode-zen
    model: gpt-5.5
    temperature: 0.7
    max_tokens: 16384

agents:
  root:
    model: zen_model
    description: Assistant using OpenCode Zen
    instruction: You are a helpful assistant.

Available Models

Free Models

These models are available at no cost:

OpenAI-Compatible (Chat Completions)

These models use the /v1/chat/completions endpoint and work directly with the opencode-zen alias:

OpenAI-Compatible (Responses API)

These models use the /v1/responses endpoint and are auto-detected by Docker Agent based on the model name:

Anthropic-Compatible (Messages API)

These models use the /v1/messages endpoint and require a custom provider definition:

To use an Anthropic-compatible model:

providers:
  opencode-zen-claude:
    provider: anthropic
    base_url: https://opencode.ai/zen
    token_key: OPENCODE_API_KEY

models:
  claude:
    provider: opencode-zen-claude
    model: claude-sonnet-4-6

agents:
  root:
    model: claude
    description: Assistant using Claude through OpenCode Zen
    instruction: You are a helpful assistant.

Google-Compatible

These models require a custom provider definition with a Google-compatible client:

To use a Google model:

providers:
  opencode-zen-gemini:
    provider: google
    base_url: https://opencode.ai/zen
    token_key: OPENCODE_API_KEY

models:
  gemini:
    provider: opencode-zen-gemini
    model: gemini-3.5-flash

agents:
  root:
    model: gemini
    description: Assistant using Gemini through OpenCode Zen
    instruction: You are a helpful assistant.

How It Works

OpenCode Zen is implemented as a built-in alias in Docker Agent:

• API Type: OpenAI-compatible (auto-detects Responses API for GPT models, Chat Completions for others)
• Base URL: https://opencode.ai/zen/v1
• Token Variable: OPENCODE_API_KEY

The same API key works for both OpenCode Go and OpenCode Zen — they are part of the same platform. Zen uses a pay-per-use billing model, while Go uses a fixed subscription.

For Anthropic-compatible models, Docker Agent uses a custom provider pointing to the Anthropic client at https://opencode.ai/zen with the same token. For Google models, a custom provider points to the Google client at https://opencode.ai/zen (the Google SDK appends its own /v1beta/models/... path segment).

Session Header

OpenCode's Go documentation asks clients to send an x-opencode-session header carrying one stable ID per conversation, which it uses to optimise routing and prompt caching. Docker Agent sends the same header on every direct request to opencode.ai, Zen included, whether the model goes through the built-in alias or a custom provider on the OpenAI, Anthropic or Google client, deriving an opaque value from the agent session so each conversation keeps the same ID, including in serve api / serve chat deployments that multiplex many conversations. Requests routed through a models gateway carry the gateway's own session header instead, and the OpenAI client's opt-in transport: websocket setting is ignored for OpenCode models, which stay on SSE so the header is always sent. On the OpenAI client you can pin your own value through provider_opts.http_headers.x-opencode-session; the Anthropic and Google clients do not read http_headers.

Differences from OpenCode Go

Usage Limits and Pricing

OpenCode Zen uses a pay-per-use model. See the OpenCode Zen documentation for current pricing. Automatic top-up and monthly usage limits are available from the console.

You can retrieve the full model catalog at any time:

curl https://opencode.ai/zen/v1/models