Configuration

Configure OpenCode programmatically via the SDK

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'
}

Sharing

share · 'manual' | 'auto' | 'disabled' · default: "manual"

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 })