OpenCode OpenCode

Setup & Config

Configuration, providers, network, and more.

Config

Using the OpenCode JSON config. You can configure OpenCode using a JSON config file.

Format

OpenCode supports both JSON and JSONC formats.

jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

Locations

OpenCode looks for configuration in multiple locations and merges them together. You can place config files at any of the following locations, each with a different precedence level.

Note

Configuration files are merged together, not replaced.

When multiple config files exist, settings from higher-precedence sources override lower-precedence ones. For example, if your global config sets "model": "anthropic/claude-sonnet-4-5" and your project config sets "model": "openai/gpt-4.1", the project config wins because it has higher precedence.

Precedence order

Configuration is resolved in the following order, from lowest to highest priority:

  1. Remote config (from .well-known/opencode) — organizational defaults
  2. Global config (~/.config/opencode/opencode.json) — user preferences
  3. Custom config (OPENCODE_CONFIG env var) — custom overrides
  4. Project config (opencode.json in project) — project-specific settings
  5. .opencode directories — agents, commands, plugins
  6. Inline config (OPENCODE_CONFIG_CONTENT env var) — runtime overrides
  7. Managed config files (/Library/Application Support/opencode/ on macOS) — admin-controlled
  8. macOS managed preferences (.mobileconfig via MDM) — highest priority, not user-overridable
Note

For subdirectories like agents, commands, and plugins, use plural names (e.g. .opencode/agents/, .opencode/commands/).

Remote

Organizations can provide default configuration for all developers via a .well-known/opencode endpoint. This is the lowest-precedence source and can be overridden by any local config.

json
{
  "mcp": {
    "jira": {
      "disabled": true
    }
  }
}

A local config can re-enable it:

json
{
  "mcp": {
    "jira": {
      "disabled": false
    }
  }
}

Global

Place your global config at ~/.config/opencode/opencode.json. This applies to all projects.

TUI-specific settings go in ~/.config/opencode/tui.json.

Per project

Add an opencode.json file in your project root to apply project-specific settings.

Tip

Place project-specific config in the project root as opencode.json. It is safe to check into Git.

OpenCode traverses up to the nearest Git directory when looking for project config.

Custom path

Set the OPENCODE_CONFIG environment variable to load config from a custom file path:

bash
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Custom directory

Set the OPENCODE_CONFIG_DIR environment variable to change the config directory:

bash
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

Managed settings

Organizations can enforce configuration that users cannot override.

File-based:

PlatformPath
macOS/Library/Application Support/opencode/
Linux/etc/opencode/
Windows%ProgramData%\opencode

macOS managed preferences: Use the ai.opencode.managed preference domain. Deploy a .mobileconfig via MDM.

Plist paths are checked for managed preference keys.

xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  http://www.apple.com/DTDs/PropertyList-1.0.dtd>
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>ai.opencode.managed</string>
      <key>PayloadIdentifier</key>
      <string>com.example.opencode.config</string>
      <key>PayloadUUID</key>
      <string>GENERATE-YOUR-OWN-UUID</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>share</key>
      <string>disabled</string>
      <key>server</key>
      <dict>
        <key>hostname</key>
        <string>127.0.0.1</string>
      </dict>
      <key>permission</key>
      <dict>
        <key>*</key>
        <string>ask</string>
        <key>bash</key>
        <dict>
          <key>*</key>
          <string>ask</string>
          <key>rm -rf *</key>
          <string>deny</string>
        </dict>
      </dict>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadIdentifier</key>
  <string>com.example.opencode</string>
  <key>PayloadUUID</key>
  <string>GENERATE-YOUR-OWN-UUID</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

MDM deployment:

Verifying: Run opencode debug config to verify managed preferences are active.

Schema

The full JSON schema is available at opencode.ai/config.json. TUI config schema is at opencode.ai/tui.json.

TUI

TUI-specific settings go in tui.json:

json
{
  "scroll_speed": 3,
  "scroll_acceleration": true,
  "diff_style": "unified",
  "mouse": true,
  "attention": true
}

You can also set the TUI config path via the OPENCODE_TUI_CONFIG environment variable.

Legacy TUI keys in the main config are deprecated. Move them to tui.json.

Server

You can configure server settings for the opencode serve and opencode web commands through the server option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Available options:

Shell

You can configure the shell used for the interactive terminal using the shell option. Compatible shells are also used for agent tool calls.

json
{
  "$schema": "https://opencode.ai/config.json",
  "shell": "pwsh"
}

If not specified, OpenCode will automatically discover and use a sensible default based on your operating system.

Tools

You can manage the tools an LLM can use through the tools option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Models

You can configure the providers and models you want to use through the provider, model and small_model options.

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

The small_model option configures a separate model for lightweight tasks like title generation. By default, OpenCode tries to use a cheaper model if one is available from your provider, otherwise it falls back to your main model.

Provider options:

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

Provider-specific options — Amazon Bedrock:

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}
Note

Bearer tokens (AWS_BEARER_TOKEN_BEDROCK or /connect) take precedence over profile-based authentication.

Policies

Use the experimental.policies option to allow or deny OpenCode actions on configured resources.

json
{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

Image attachments

OpenCode normalizes image attachments before sending them to the model. By default, images are resized when they exceed 2000x2000 pixels or 5242880 base64 bytes.

json
{
  "$schema": "https://opencode.ai/config.json",
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

Themes

Set your UI theme in tui.json.

json
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

Agents

You can configure specialized agents for specific tasks through the agent option.

jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

You can also define agents using markdown files in ~/.config/opencode/agents/ or .opencode/agents/.

Default agent

You can set the default agent using the default_agent option. This determines which agent is used when none is explicitly specified.

json
{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

The default agent must be a primary agent (not a subagent). This can be a built-in agent like "build" or "plan", or a custom agent you've defined. If the specified agent doesn't exist or is a subagent, OpenCode will fall back to "build" with a warning.

Sharing

You can configure the share feature through the share option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

This takes:

Commands

You can configure custom commands for repetitive tasks through the command option.

jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

You can also define commands using markdown files in ~/.config/opencode/commands/ or .opencode/commands/.

Keybinds

Customize TUI keyboard shortcuts in tui.json with keybinds.

json
{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "command_list": "ctrl+p"
  }
}

keybinds is merged with built-in defaults, so you only need to configure the shortcuts you want to change.

Snapshot

OpenCode uses snapshots to track file changes during agent operations, enabling you to undo and revert changes within a session. Snapshots are enabled by default.

json
{
  "$schema": "https://opencode.ai/config.json",
  "snapshot": false
}

Note that disabling snapshots means changes made by the agent cannot be rolled back through the UI.

Autoupdate

OpenCode will automatically download any new updates when it starts up. You can disable this with the autoupdate option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

If you don't want updates but want to be notified when a new version is available, set autoupdate to "notify". Notice that this only works if it was not installed using a package manager such as Homebrew.

Formatters

You can enable and configure code formatters through the formatter option. Omit it to keep formatters disabled.

json
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true
}

Use an object to keep built-ins enabled while configuring overrides or custom formatters:

json
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

LSP Servers

You can enable and configure LSP servers through the lsp option. Omit it to keep LSP disabled.

json
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}

Use an object to keep built-ins enabled while configuring overrides:

json
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

Permissions

By default, OpenCode allows all operations without requiring explicit approval. You can change this using the permission option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Compaction

You can control context compaction behavior through the compaction option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

Watcher

You can configure file watcher ignore patterns through the watcher option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

MCP servers

You can configure MCP servers you want to use through the mcp option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

Plugins

Plugins extend OpenCode with custom tools, hooks, and integrations. Place plugin files in .opencode/plugins/ or ~/.config/opencode/plugins/. You can also load plugins from npm through the plugin option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Instructions

You can configure the instructions for the model you're using through the instructions option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

This takes an array of paths and glob patterns to instruction files.

Disabled providers

You can disable providers that are loaded automatically through the disabled_providers option.

json
{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}
Note

The disabled_providers takes priority over enabled_providers.

Enabled providers

You can specify an allowlist of providers through the enabled_providers option. When set, only the specified providers will be enabled.

json
{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

Experimental

The experimental key contains options that are under active development.

json
{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}
Caution

Experimental options are not stable. They may change or be removed without notice.

Variables

You can use variable substitution in your config files to reference environment variables and file contents.

Env vars

Use {env:VARIABLE_NAME} to substitute environment variables:

json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

If the environment variable is not set, it will be replaced with an empty string.

Files

Use {file:path/to/file} to substitute the contents of a file:

json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

File paths can be:

These are useful for keeping sensitive data like API keys in separate files, including large instruction files without cluttering your config, and sharing common configuration snippets across multiple config files.

Providers

Using any LLM provider in OpenCode. OpenCode uses the AI SDK and Models.dev to support 75+ LLM providers.

To add a provider you need to:

  1. Add the API keys for the provider using the /connect command.
  2. Configure the provider in your OpenCode config.

Credentials

When you add a provider's API keys with the /connect command, they are stored in ~/.local/share/opencode/auth.json.

You can customize the base URL for any provider by setting the baseURL option:

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  }
}

OpenCode Zen is a list of models provided by the OpenCode team that have been tested and verified to work well with OpenCode. Run /connect, select OpenCode Zen, and head to opencode.ai/auth.

OpenCode Go is a low cost subscription plan that provides reliable access to popular open coding models. Run /connect and follow the authentication flow.

Directory

Note

Want to add a new provider? Submit a PR to the OpenCode repository.

Amazon Bedrock

To use Amazon Bedrock with OpenCode, head over to the Model catalog in the Amazon Bedrock console and request access to the models you want.

Tip

You need to have access to the model you want in Amazon Bedrock.

Environment Variables (Quick Start):

bash
# Option 1: Using AWS access keys
AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode
# Option 2: Using named AWS profile
AWS_PROFILE=my-profile opencode
# Option 3: Using Bedrock bearer token
AWS_BEARER_TOKEN_BEDROCK=XXX opencode

Or add them to your bash profile:

bash
export AWS_PROFILE=my-dev-profile
export AWS_REGION=us-east-1

Configuration File (Recommended):

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile"
      }
    }
  }
}

Available options:

Tip

Configuration file options take precedence over environment variables.

Advanced: VPC Endpoints

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "production",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}
Note

The endpoint option is an alias for the generic baseURL option, using AWS-specific terminology. If both endpoint and baseURL are specified, endpoint takes precedence.

Authentication Methods:

Authentication Precedence:

  1. Bearer Token — AWS_BEARER_TOKEN_BEDROCK environment variable or token from /connect command
  2. AWS Credential Chain — Profile, access keys, shared credentials, IAM roles, Web Identity Tokens (EKS IRSA), instance metadata
Note

When a bearer token is set (via /connect or AWS_BEARER_TOKEN_BEDROCK), it takes precedence over all AWS credential methods including configured profiles.

Custom inference profiles:

Note

For custom inference profiles, use the model and provider name in the key and set the id property to the ARN. This ensures correct caching.

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "models": {
        "anthropic-claude-sonnet-4.5": {
          "id": "arn:aws:bedrock:us-east-1:xxx:application-inference-profile/yyy"
        }
      }
    }
  }
}

Anthropic

Once you've signed up, run the /connect command and select Anthropic. You can select the Claude Pro/Max option and it will open your browser and ask you to authenticate.

/connect

There are plugins that allow you to use your Claude Pro/Max models with OpenCode. Anthropic explicitly prohibits this. Previous versions of OpenCode came bundled with these plugins but that is no longer the case as of 1.3.0.

Other companies support freedom of choice with developer tooling — you can use the following subscriptions in OpenCode with zero setup: ChatGPT Plus, GitHub Copilot, GitLab Duo.

GitHub Copilot

To use your GitHub Copilot subscription with OpenCode:

Note

Some models might need a Pro+ subscription to use.

Run the /connect command and search for GitHub Copilot:

/connect

Navigate to github.com/login/device and enter the code shown in your terminal.

Google Vertex AI

To use Google Vertex AI with OpenCode, head over to the Model Garden in the Google Cloud Console and check the models available in your region.

Note

You need to have a Google Cloud project with Vertex AI API enabled.

Set the required environment variables:

bash
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json GOOGLE_CLOUD_PROJECT=your-project-id opencode

Or add them to your bash profile:

bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=your-project-id
export VERTEX_LOCATION=global
Tip

The global region improves availability and reduces errors at no extra cost. Use regional endpoints (e.g., us-central1) for data residency requirements.

Groq

Head over to the Groq console, click Create API Key, and copy the key.

/connect

Search for Groq and enter your API key.

Ollama

You can configure OpenCode to use local models through Ollama.

Tip

Ollama can automatically configure itself for OpenCode. See the Ollama integration docs for details.

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

In this example:

Tip

If tool calls aren't working, try increasing num_ctx in Ollama. Start around 16k - 32k.

OpenAI

We recommend signing up for ChatGPT Plus or Pro.

Once you've signed up, run the /connect command and select OpenAI:

/connect

Select the ChatGPT Plus/Pro option and it will open your browser and ask you to authenticate. If you already have an API key, select Manually enter API Key instead.

OpenRouter

Head over to the OpenRouter dashboard, click Create API Key, and copy the key.

/connect

Many OpenRouter models are preloaded by default. You can also add additional models through your config:

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "somecoolnewmodel": {}
      }
    }
  }
}

Provider routing example:

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2": {
          "options": {
            "provider": {
              "order": ["baseten"],
              "allow_fallbacks": false
            }
          }
        }
      }
    }
  }
}

xAI

Three ways to authenticate: a SuperGrok subscription via browser OAuth, the same SuperGrok subscription via a headless device-code flow (for VPS / SSH / Docker), or a pay-as-you-go API key from the xAI console.

Other providers

OpenCode also supports the following providers. Use /connect and search for the provider name.

Custom provider

To add any OpenAI-compatible provider that's not listed in the /connect command:

Tip

You can use any OpenAI-compatible provider with OpenCode. Most modern AI providers offer OpenAI-compatible APIs.

Run the /connect command and scroll down to Other. Enter a unique ID for the provider, then your API key.

Note

Choose a memorable ID — you'll use this in your config file.

Create or update your opencode.json file:

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My AI ProviderDisplay Name",
      "options": {
        "baseURL": "https://api.myprovider.com/v1"
      },
      "models": {
        "my-model-name": {
          "name": "My Model Display Name"
        }
      }
    }
  }
}

Configuration options:

Advanced example with apiKey, headers, and model limit options:

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My AI ProviderDisplay Name",
      "options": {
        "baseURL": "https://api.myprovider.com/v1",
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "headers": {
          "Authorization": "Bearer custom-token"
        }
      },
      "models": {
        "my-model-name": {
          "name": "My Model Display Name",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        }
      }
    }
  }
}

Configuration details:

The limit fields allow OpenCode to understand how much context you have left. Standard providers pull these from models.dev automatically.

Troubleshooting custom providers:

Network

Proxy

OpenCode respects the standard proxy environment variables:

bash
export HTTPS_PROXY="http://proxy.example.com:8080"
export HTTP_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
Caution

The TUI starts a local HTTP server. Make sure your proxy configuration does not intercept local traffic. Add 127.0.0.1 and localhost to NO_PROXY.

Basic auth in proxy URL:

bash
export HTTPS_PROXY="http://user:password@proxy.example.com:8080"
Caution

Avoid hardcoding passwords in shared config files or scripts. Use environment variables set in your shell profile or a secrets manager instead.

Custom certificates

If your network uses a custom CA or self-signed certificates, set the NODE_EXTRA_CA_CERTS environment variable:

bash
export NODE_EXTRA_CA_CERTS="/path/to/custom-ca.crt"

Enterprise

OpenCode Enterprise is for organizations that want to ensure that their code and data never leaves their infrastructure. It can do this by using a centralized config that integrates with your SSO and internal AI gateway.

Note

OpenCode does not store any of your code or context data.

To get started with OpenCode Enterprise:

  1. Do a trial internally with your team.
  2. Contact us to discuss pricing and implementation options.

Trial

OpenCode is open source and does not store any of your code or context data, so your developers can simply get started and carry out a trial.

Data handling

OpenCode does not store your code or context data. All processing happens locally or through direct API calls to your AI provider. This means that as long as you are using a provider you trust, or an internal AI gateway, you can use OpenCode securely.

Sharing conversations

If a user enables the /share feature, the conversation and the data associated with it are sent to the service used to host share pages. We recommend disabling this for your trial:

json
{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled"
}

Code ownership

You own all code produced by OpenCode. There are no licensing restrictions or ownership claims.

Deployment

Once you have completed your trial and you are ready to use OpenCode at your organization, you can contact us to discuss pricing and implementation options.

Central config

A single central config for your entire organization can be set up. This centralized config can integrate with your SSO provider and ensures all users access only your internal AI gateway.

SSO integration

Through the central config, OpenCode can integrate with your organization's SSO provider for authentication. This allows OpenCode to obtain credentials for your internal AI gateway through your existing identity management system.

Internal AI gateway

With the central config, OpenCode can be configured to use only your internal AI gateway. You can also disable all other AI providers, ensuring all requests go through your organization's approved infrastructure.

Self-hosting

While we recommend disabling the share pages to ensure your data never leaves your organization, self-hosted share pages on your infrastructure are on the roadmap.

FAQ

Q: What is OpenCode Enterprise?

OpenCode Enterprise is for organizations that want to ensure that their code and data never leaves their infrastructure. It can do this by using a centralized config that integrates with your SSO and internal AI gateway.

Q: How do I get started with OpenCode Enterprise?

Simply start with an internal trial with your team. OpenCode by default does not store your code or context data, making it easy to get started. Then contact us to discuss pricing and implementation options.

Q: How does enterprise pricing work?

We offer per-seat enterprise pricing. If you have your own LLM gateway, we do not charge for tokens used.

Q: Is my data secure with OpenCode Enterprise?

Yes. OpenCode does not store your code or context data. All processing happens locally or through direct API calls to your AI provider. With central config and SSO integration, your data remains secure within your organization's infrastructure.

Q: Can we use our own private NPM registry?

OpenCode supports private npm registries through Bun's native .npmrc file support. Ensure developers are authenticated before running OpenCode:

npm login --registry=https://your-company.jfrog.io/api/npm/npm-virtual/
Caution

You must be logged into the private registry before running OpenCode.

Troubleshooting

Logs

Log files are written to:

Log files are named with timestamps (e.g., 2025-01-09T123456.log) and the most recent 10 log files are kept.

You can set the log level with the --log-level command-line option to get more detailed debug information:

bash
opencode --log-level DEBUG

Storage: OpenCode stores session data and other application data on disk at:

This directory contains:

Uninstall: To uninstall the OpenCode CLI and remove its related files:

opencode uninstall

Desktop app

OpenCode Desktop runs a local OpenCode server (the opencode-cli sidecar) in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.

Quick checks

Disable plugins

If the desktop app is crashing on launch, hanging, or behaving strangely, start by disabling plugins.

Check the global config: Open your global config file and look for a plugin key. Temporarily disable them by setting it to an empty array:

json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

Check plugin directories: Temporarily move these out of the way and restart:

Clear cache

Quit OpenCode Desktop completely, then delete the cache directory:

Fix server connection issues

If you see a "Connection Failed" dialog, check for a custom server URL. From the Home screen, click the server name to open the Server picker. In the Default server section, click Clear.

If your opencode.json(c) contains a server section, temporarily remove it and restart. If you have OPENCODE_PORT set in your environment, unset it or pick a free port.

Platform-specific issues

Linux (Wayland): If the app is blank/crashing on Wayland, try launching with OC_ALLOW_WAYLAND=1.

Windows (WebView2): OpenCode Desktop requires the Microsoft Edge WebView2 Runtime. If the app opens to a blank window or won't start, install/update WebView2 and try again.

Common issues

OpenCode won't start

Authentication issues

Model not available

If you encounter ProviderModelNotFoundError, you are most likely incorrectly referencing a model. Models should be referenced like so: <providerId>/<modelId>

Examples:

To figure out what models you have access to, run opencode models

ProviderInitError

If you encounter a ProviderInitError, you likely have an invalid or corrupted configuration. To resolve this:

  1. First, verify your provider is set up correctly by following the providers guide
  2. If the issue persists, try clearing your stored configuration:
rm -rf ~/.local/share/opencode

On Windows, press WIN+R and delete: %USERPROFILE%\.local\share\opencode

Then re-authenticate with your provider using the /connect command.

AI_APICallError and provider package issues

If you encounter API call errors, this may be due to outdated provider packages. OpenCode dynamically installs provider packages and caches them locally. To resolve:

  1. Clear the provider package cache:
rm -rf ~/.cache/opencode

On Windows, press WIN+R and delete: %USERPROFILE%\.cache\opencode

Then restart OpenCode to reinstall the latest provider packages.

Copy/paste not working on Linux

Linux users need one of the following clipboard utilities installed:

For X11 systems:

apt install -y xclip
# or
apt install -y xsel

For Wayland systems:

apt install -y wl-clipboard

For headless environments:

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

Windows

Run OpenCode on Windows using WSL for the best experience.

While OpenCode can run directly on Windows, we recommend using Windows Subsystem for Linux (WSL) for the best experience. WSL provides a Linux environment that works seamlessly with OpenCode's features.

Why WSL? WSL offers better file system performance, full terminal support, and compatibility with development tools that OpenCode relies on.

Setup

1. Install WSL

If you haven't already, install WSL using the official Microsoft guide.

2. Install OpenCode in WSL

Once WSL is set up, open your WSL terminal and install OpenCode using one of the installation methods:

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

3. Use OpenCode from WSL

Navigate to your project directory (access Windows files via /mnt/c/, /mnt/d/, etc.) and run OpenCode:

bash
cd /mnt/c/Users/YourName/project
opencode

Desktop + WSL

If you prefer using the OpenCode Desktop app but want to run the server in WSL:

1. Start the server in WSL with --hostname 0.0.0.0 to allow external connections:

bash
opencode serve --hostname 0.0.0.0 --port 4096

2. Connect the Desktop app to http://localhost:4096

Note

If localhost does not work in your setup, connect using the WSL IP address instead (from WSL: hostname -I) and use http://<wsl-ip>:4096.

Caution

When using --hostname 0.0.0.0, set OPENCODE_SERVER_PASSWORD to secure the server.

bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve --hostname 0.0.0.0

Web Client + WSL: For the best web experience on Windows, run opencode web in the WSL terminal rather than PowerShell:

bash
opencode web --hostname 0.0.0.0

Access from your Windows browser at http://localhost:<port> (OpenCode prints the URL).

Accessing Windows Files: WSL can access all your Windows files through the /mnt/ directory:

Tip

For the smoothest experience, consider cloning/copying your repo into the WSL filesystem (for example under ~/code/) and running OpenCode there.

Tips

Edit page · Found a bug? · Discord
©2026 Anomaly