Config Reference

Quick reference for all configuration options in opencode.json and tui.json.

opencode.json — Core Configuration

Model Settings

{
  "model": "anthropic/claude-sonnet-4",
  "small_model": "anthropic/claude-haiku-3-5",
  "default_agent": "build"
}

Option	Type	Default	Description
model	string	"anthropic/claude-sonnet-4"	Primary model in provider/model format
small_model	string	"anthropic/claude-haiku-3-5"	Lightweight model for compaction and subtasks
default_agent	string	"build"	Default agent used on startup

Provider Configuration

{
  "provider": {
    "ollama": {
      "baseURL": "http://localhost:11434/api",
      "timeout": 60000,
      "headers": {
        "X-Custom": "value"
      },
      "models": ["llama3", "codellama"]
    }
  }
}

Option	Type	Description
baseURL	string	API endpoint URL for the provider
timeout	number	Request timeout in milliseconds
headers	object	Custom HTTP headers for all requests
models	string[]	Whitelist of specific model names to use

Tool Permissions

{
  "permission": {
    "read_file": "allow",
    "write_file": "allow",
    "run_command": "ask",
    "glob": "allow",
    "grep": "allow",
    "edit": "allow",
    "terminal": "deny",
    "search": "allow",
    "web_fetch": "ask"
  }
}

Permission levels:

Level	Description
"allow"	Tool executes automatically without confirmation
"ask"	Prompt user for approval before execution
"deny"	Tool cannot be used

Granular pattern-based permissions:

{
  "permission": {
    "write_file": {
      "allow": ["src/**/*.ts", "*.md"],
      "deny": ["*.env", "node_modules/**"]
    },
    "run_command": {
      "allow": ["npm test", "npm run build"],
      "ask": ["git *"],
      "deny": ["rm -rf *"]
    }
  }
}

Agent Definitions

{
  "agent": {
    "build": {
      "mode": "full",
      "model": "anthropic/claude-sonnet-4",
      "system": "You are a skilled software engineer.",
      "permission": {
        "run_command": "deny"
      },
      "temperature": 0.3,
      "steps": 50
    },
    "plan": {
      "mode": "plan",
      "model": "anthropic/claude-sonnet-4",
      "temperature": 0.1,
      "steps": 30
    }
  }
}

Attribute	Type	Description
mode	"full" | "plan"	Agent operating mode
model	string	Model override for this agent
system	string	System prompt override
permission	object	Tool permission overrides
temperature	number	Model temperature (0.0 - 1.0)
steps	number	Maximum tool call steps per response

Custom Commands

{
  "command": {
    "test": {
      "template": "Run the tests for this project and report results",
      "description": "Run project tests",
      "agent": "build",
      "model": "anthropic/claude-haiku-3-5"
    },
    "review": {
      "template": "Review the latest git changes for bugs, security issues, and style problems",
      "description": "Review latest changes"
    }
  }
}

Formatter Configuration

{
  "formatter": true
}

Or per-language:

{
  "formatter": {
    "typescript": "prettier",
    "python": "black",
    "rust": "rustfmt",
    "go": "gofmt"
  }
}

LSP Configuration

{
  "lsp": true
}

Or per-language:

{
  "lsp": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "python": true
  }
}

MCP Servers

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "enabled": true
    },
    "github": {
      "type": "url",
      "url": "https://mcp.github.com/sse",
      "enabled": false
    }
  }
}

Plugins

{
  "plugin": [
    "opencode-helicone-session",
    "@my-org/custom-plugin",
    "./.opencode/plugins/internal.mjs"
  ]
}

Instructions (Rules)

{
  "instructions": [
    "./AGENTS.md",
    "./.opencode/rules/*.md"
  ]
}

Update Behavior

{
  "autoupdate": true
}

Value	Behavior
true	Auto-download and install updates
false	Never check for updates
"notify"	Check and notify, but do not auto-install

Snapshots (Undo/Redo)

{
  "snapshot": true
}

When enabled, OpenCode creates git-style snapshots for each AI change, supporting /undo and /redo commands.

Server Configuration

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Sharing

{
  "share": "manual"
}

Value	Description
"manual"	Share only on explicit /share command
"auto"	Auto-share all new conversations
"disabled"	Disable sharing entirely

Provider Filtering

{
  "disabled_providers": ["openai", "google"],
  "enabled_providers": ["anthropic", "ollama"]
}

Only one of disabled_providers or enabled_providers should be used.

Shell

{
  "shell": "pwsh"
}

Override the default shell used for command execution.

tui.json — UI Configuration

Theme

{
  "theme": "catppuccin-mocha"
}

Built-in themes include default, dark, light, catppuccin-latte, catppuccin-mocha, nord, dracula, monokai, solarized-dark, solarized-light.

Keybindings

{
  "keybinds": [
    {
      "keys": ["ctrl+x", "c"],
      "action": "compact"
    }
  ]
}

See Keyboard Shortcuts for the full action reference.

Other UI Settings

{
  "scroll_speed": 3,
  "mouse": true,
  "diff_style": "auto"
}

Option	Type	Default	Description
scroll_speed	number	3	Lines per scroll tick
mouse	boolean	true	Enable mouse capture for scrolling and clicking
diff_style	"auto" | "stacked"	"auto"	Diff display mode

Attention (Notifications)

{
  "attention": {
    "sound": true,
    "notifications": true
  }
}

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	API key for Anthropic Claude models
OPENAI_API_KEY	API key for OpenAI models
GOOGLE_GENERATIVE_AI_API_KEY	API key for Google Gemini models
GROQ_API_KEY	API key for Groq models
TOGETHER_API_KEY	API key for Together AI models
MISTRAL_API_KEY	API key for Mistral models
COHERE_API_KEY	API key for Cohere models
FIREWORKS_API_KEY	API key for Fireworks AI models
AZURE_OPENAI_KEY	API key for Azure OpenAI
OPENCODE_SERVER_PASSWORD	HTTP Basic auth password for server mode
OPENCODE_GIT_BASH_PATH	Path to Git Bash executable (Windows)
HTTP_PROXY / HTTPS_PROXY	Proxy server URL for outbound connections
NO_PROXY	Hosts to exclude from proxy routing
NODE_TLS_REJECT_UNAUTHORIZED	Set to 0 to disable TLS verification (not recommended)