Configuration

Overview

The SDK allows you to configure OpenCode programmatically. You can pass configuration when creating a server instance, or update it at runtime via the API.

Initial Configuration

Pass configuration when creating an OpenCode instance:

import { createOpencode } from '@opencode-ai/sdk'

const { client, server } = await createOpencode({
  config: {
    model: 'anthropic/claude-3-5-sonnet-20241022',
    logLevel: 'INFO',
    theme: 'dark',
    agent: {
      build: {
        model: 'anthropic/claude-3-5-sonnet-20241022',
        temperature: 0.7,
      },
    },
  },
})

The configuration is passed via the OPENCODE_CONFIG_CONTENT environment variable and merged with any existing opencode.json file.

Runtime Configuration

Update configuration at runtime:

// Get current configuration
const config = await client.config.get()
console.log(config.data.model)

// Update configuration
await client.config.update({
  body: {
    model: 'anthropic/claude-3-5-sonnet-20241022',
    logLevel: 'DEBUG',
  },
})

Configuration Options

Model Selection

model

string

Default model to use (format: provider/model)

config: {
  model: 'anthropic/claude-3-5-sonnet-20241022'
}

small_model

string

Small model for tasks like title generation

config: {
  small_model: 'anthropic/claude-3-haiku-20240307'
}

Logging

logLevel

'DEBUG' | 'INFO' | 'WARN' | 'ERROR'

default:"INFO"

Log level for server output

config: {
  logLevel: 'DEBUG'
}

Agent Configuration

agent

Record<string, AgentConfig>

Configure individual agents

config: {
  agent: {
    build: {
      model: 'anthropic/claude-3-5-sonnet-20241022',
      temperature: 0.7,
      maxSteps: 20,
      permission: {
        edit: 'allow',
        bash: 'ask',
      },
    },
    plan: {
      model: 'anthropic/claude-3-opus-20240229',
      temperature: 0.5,
    },
  },
}

AgentConfig Properties

model

string

Model for this agent (overrides global model)

temperature

number

Temperature for model sampling (0-1)

top_p

number

Top-p sampling parameter

maxSteps

number

Maximum agentic iterations before forcing text-only response

description

string

Description of when to use this agent

mode

'subagent' | 'primary' | 'all'

default:"all"

When this agent is available

color

string

Hex color code for the agent (e.g., #FF5733)

prompt

string

Custom system prompt for this agent

tools

Record<string, boolean>

Enable/disable specific tools

tools: {
  bash: true,
  webfetch: false,
}

permission

PermissionConfig

Permission settings

permission: {
  edit: 'allow',      // File editing
  bash: 'ask',        // Shell commands
  webfetch: 'allow',  // Web fetching
  doom_loop: 'deny',  // Prevent infinite loops
}

Values: 'ask' | 'allow' | 'deny'

Provider Configuration

provider

Record<string, ProviderConfig>

Configure custom providers or override defaults

config: {
  provider: {
    anthropic: {
      options: {
        apiKey: 'your-api-key',
        baseURL: 'https://api.anthropic.com',
      },
    },
    custom: {
      api: 'https://api.example.com',
      name: 'Custom Provider',
      models: {
        'my-model': {
          id: 'my-model-id',
          name: 'My Model',
          cost: { input: 0.01, output: 0.03 },
          limit: { context: 128000, output: 4096 },
        },
      },
    },
  },
}

MCP Servers

mcp

Record<string, McpConfig>

Configure Model Context Protocol servers

config: {
  mcp: {
    filesystem: {
      type: 'local',
      command: ['npx', '-y', '@modelcontextprotocol/server-filesystem', '/path'],
      enabled: true,
    },
    github: {
      type: 'remote',
      url: 'https://mcp.example.com',
      enabled: true,
    },
  },
}

Commands

command

Record<string, CommandConfig>

Define custom commands

config: {
  command: {
    review: {
      template: 'Review the code in {{0}} for issues',
      description: 'Code review',
      agent: 'build',
    },
    test: {
      template: 'Write tests for {{0}}',
      description: 'Generate tests',
      subtask: true,
    },
  },
}

Plugins

plugin

string[]

Load custom plugins

config: {
  plugin: [
    './plugins/custom-tool.ts',
    '@company/opencode-plugin',
  ],
}

TUI Settings

tui

TuiConfig

Terminal UI settings

config: {
  tui: {
    scroll_speed: 3,
    scroll_acceleration: { enabled: true },
    diff_style: 'auto',
  },
}

theme

string

Theme name

config: {
  theme: 'dark'
}

Session sharing behavior

config: {
  share: 'auto'  // Auto-share all sessions
}

Other Options

username

string

Custom username for display

snapshot

boolean

Enable/disable snapshots

autoupdate

boolean | 'notify'

Auto-update behavior

instructions

string[]

Additional instruction files to include

config: {
  instructions: ['STYLE_GUIDE.md', '.cursorrules']
}

tools

Record<string, boolean>

Global tool enable/disable

config: {
  tools: {
    bash: true,
    webfetch: true,
  },
}

permission

PermissionConfig

Global permission settings (can be overridden per agent)

Examples

Development Configuration

const { client, server } = await createOpencode({
  config: {
    logLevel: 'DEBUG',
    model: 'anthropic/claude-3-5-sonnet-20241022',
    agent: {
      build: {
        permission: {
          edit: 'allow',
          bash: 'allow',
        },
      },
    },
  },
})

Production Configuration

const { client, server } = await createOpencode({
  config: {
    logLevel: 'ERROR',
    model: 'anthropic/claude-3-5-sonnet-20241022',
    share: 'disabled',
    permission: {
      edit: 'ask',
      bash: 'ask',
      webfetch: 'ask',
    },
  },
})

Custom Provider

const { client, server } = await createOpencode({
  config: {
    provider: {
      'my-provider': {
        api: 'https://api.example.com/v1',
        name: 'My Provider',
        options: {
          apiKey: process.env.API_KEY,
        },
        models: {
          'my-model': {
            id: 'my-model-v1',
            name: 'My Custom Model',
            cost: { input: 0.01, output: 0.03 },
            limit: { context: 100000, output: 4096 },
          },
        },
      },
    },
    model: 'my-provider/my-model',
  },
})

Multi-Agent Setup

const { client, server } = await createOpencode({
  config: {
    agent: {
      architect: {
        model: 'anthropic/claude-3-opus-20240229',
        description: 'High-level architecture and design',
        temperature: 0.3,
        mode: 'primary',
      },
      builder: {
        model: 'anthropic/claude-3-5-sonnet-20241022',
        description: 'Implementation and coding',
        temperature: 0.7,
        mode: 'all',
        permission: {
          edit: 'allow',
          bash: 'ask',
        },
      },
      tester: {
        model: 'anthropic/claude-3-5-sonnet-20241022',
        description: 'Testing and validation',
        temperature: 0.5,
        mode: 'subagent',
      },
    },
  },
})

Getting Provider Information

Retrieve information about available providers and models:

// List all providers and their default models
const info = await client.config.providers()

console.log('Available providers:')
for (const provider of info.data.providers) {
  console.log(`- ${provider.name} (${provider.id})`)
  console.log(`  Models: ${Object.keys(provider.models).length}`)
}

console.log('\nDefaults:', info.data.default)

Type Safety

All configuration is fully typed:

import type { Config, AgentConfig } from '@opencode-ai/sdk'

const config: Config = {
  model: 'anthropic/claude-3-5-sonnet-20241022',
  agent: {
    build: {
      temperature: 0.7,
      maxSteps: 20,
    } satisfies AgentConfig,
  },
}

const { client, server } = await createOpencode({ config })

JavaScript SDK

Plugin API

Overview

Initial Configuration

Runtime Configuration

Configuration Options

Model Selection

Logging

Agent Configuration

AgentConfig Properties

Provider Configuration

MCP Servers

Commands

Plugins

TUI Settings

Other Options

Examples

Development Configuration

Production Configuration

Custom Provider

Multi-Agent Setup

Getting Provider Information

Type Safety

JavaScript SDK

Plugin API

​Overview

​Initial Configuration

​Runtime Configuration

​Configuration Options

​Model Selection

​Logging

​Agent Configuration

​AgentConfig Properties

​Provider Configuration

​MCP Servers

​Commands

​Plugins

​TUI Settings

​Sharing

​Other Options

​Examples

​Development Configuration

​Production Configuration

​Custom Provider

​Multi-Agent Setup

​Getting Provider Information

​Type Safety

Overview

Initial Configuration

Runtime Configuration

Configuration Options

Model Selection

Logging

Agent Configuration

AgentConfig Properties

Provider Configuration

MCP Servers

Commands

Plugins

TUI Settings

Sharing

Other Options

Examples

Development Configuration

Production Configuration

Custom Provider

Multi-Agent Setup

Getting Provider Information

Type Safety