OpenCode

What is OpenCode?

OpenCode is an open-source AI coding agent designed to bring powerful AI assistance directly to your development workflow. It's a Go-based CLI application that brings AI assistance to your terminal, providing a TUI (Terminal User Interface) for intelligent coding assistance. It's available as a terminal-based interface, desktop application, or IDE extension, helping developers write, understand, and improve code more efficiently.

Key features:

• Multi-Platform Support Available as a terminal-based interface, desktop application, or IDE extension to fit your preferred development environment.

• Flexible LLM Provider Support Works with any LLM provider by configuring API keys, including Claude, GPT, Gemini, and any OpenAI-compatible endpoints.

• Intelligent Code Generation Produces high-quality code snippets, functions, and modules based on natural-language prompts.

• Built-in Agents Comes with two built-in primary agents (Build and Plan) that you can customize or extend with your own.

• Custom Tools Support Define your own functions that the LLM can call through custom tools in your config file.

• Custom Rules & Instructions Provide custom instructions through an AGENTS.md file, similar to Cursor's rules.

• GitHub Integration Install the GitHub agent directly in your repository for CI/CD workflows.

---

Integrating OpenCode with nexos.ai

To connect your nexos.ai API Gateway with OpenCode, follow these steps:

1. Install OpenCode

OpenCode can be installed using multiple methods:

Using the install script (recommended):

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

Using Homebrew (macOS/Linux):

We recommend using the OpenCode tap for the most up-to-date releases. The official brew install opencode formula is maintained by the Homebrew team and may lag behind:

brew install anomalyco/tap/opencode

Using npm:

npm install -g opencode

Desktop Application:

OpenCode is also available as a desktop application. Install via Homebrew cask:

brew install --cask opencode-desktop

Or download directly from opencode.ai/download.

---

2. Configuration

OpenCode uses JSON configuration files to manage providers and settings. The configuration file is not created automatically during installation — you need to create it manually. The configuration supports both JSON and JSONC (JSON with Comments) formats.

Configuration file locations (in order of precedence):

• $HOME/.opencode.json

• $XDG_CONFIG_HOME/opencode/.opencode.json

• ./.opencode.json (project root — highest precedence)

You can also specify a custom config directory using the OPENCODE_CONFIG_DIR environment variable.

To create the global config:

mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json

Then add the nexos.ai provider configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "nexosai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "nexos.ai",
      "options": {
        "baseURL": "https://api.nexos.ai/v1"
      },
      "models": {
        "Claude Opus 4.5": {},
        "claude-haiku-4-5-20251001": {},
        "gpt-4.1": {},
        "gpt-4o-mini": {},
        "gemini-2.5-pro": {}
      }
    }
  },
  "model": "nexosai/Claude Opus 4.5",
  "small_model": "nexosai/claude-haiku-4-5-20251001"
}

Configuration breakdown:

• npm: The SDK package to use — @ai-sdk/openai-compatible is used for any OpenAI-compatible API

• name: The display name for the provider in the UI

• options.baseURL: The endpoint for the API (nexos.ai gateway)

• models: An object where each key is a model name; values can be empty {} or include optional properties like maxTokens (defaults to 32000)

• model: The active model in format provider-key/model-name

• small_model: Model used for lighter tasks to optimize costs

Tip: The config file has a schema defined at opencode.ai/config.json — your editor should be able to validate and autocomplete based on the schema.

Finding Available Models: You can fetch all available models from your nexos.ai gateway using the API endpoint GET /v1/models. See the https://docs.nexos.ai/gateway-api#get-v1-models for details.

---

3. Configure API Credentials

API keys are securely stored separately from your configuration. To add your nexos.ai API key, use the /connect command within OpenCode:

opencode

Once OpenCode starts, run:

/connect

1. Select "Other" to add a custom provider

2. Enter nexosai as the provider name (must match the key in your config)

3. Paste your nexos.ai team/user API key

The key will be securely stored in ~/.local/share/opencode/auth.json.

Alternative: Manual auth.json configuration

You can also manually create or edit the auth file:

mkdir -p ~/.local/share/opencode
touch ~/.local/share/opencode/auth.json

Then add your API key:

{
  "nexosai": "{YOUR_TEAM_API_KEY}"
}

---

4. Start Using OpenCode with nexos.ai

Launch OpenCode in your terminal:

opencode

OpenCode will now route all AI requests through the nexos.ai API Gateway, giving you access to multiple LLM providers through a single, unified endpoint.

---

Advanced Configuration

Built-in Agents Configuration

OpenCode comes with two built-in primary agents: Build and Plan.

• Build: The default primary agent with all tools enabled. It can read and write files, run commands, and make changes to your codebase.

• Plan: A restricted agent that handles planning and code analysis without making changes. Tool access is limited so it can only suggest how to implement features.

You can customize the built-in agents using the agent field (singular) in your configuration. Each agent supports the following options:

Option	Description
model	The model to use for this agent (e.g., nexosai/Claude Opus 4.5)
prompt	Custom system prompt for the agent
prompt_append	Additional text to append to the default prompt
temperature	Sampling temperature for the model
top_p	Top-p sampling parameter
tools	Object to enable/disable specific tools (set to true or false)
disable	Set to true to disable this agent entirely
description	Description shown in the UI

Example configuration with agent customization:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "nexosai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "nexos.ai",
      "options": {
        "baseURL": "https://api.nexos.ai/v1"
      },
      "models": {
        "Claude Opus 4.5": {},
        "claude-haiku-4-5-20251001": {},
        "gpt-4.1": {}
      }
    }
  },
  "model": "nexosai/claude-haiku-4-5-20251001",
  "small_model": "nexosai/gpt-4o-mini",
  "agent": {
    "plan": {
      "model": "nexosai/Claude Opus 4.5",
      "description": "Strategic planning with high-capability model",
      "prompt_append": "Always consider security implications in your plans."
    }
  }
}

Custom Agents with Markdown Files

For creating entirely new custom agents, use markdown files placed in dedicated directories:

• Global: ~/.config/opencode/agents/

• Per-project: .opencode/agents/

The markdown file name becomes the agent name. For example, code-reviewer.md creates a code-reviewer agent.

Example ~/.config/opencode/agents/code-reviewer.md:

---
model: nexosai/Claude Opus 4.5
description: Senior code reviewer focusing on security
tools:
  write: false
  bash: false
---

You are a senior code reviewer focusing on security and performance.
Review code for potential vulnerabilities, performance bottlenecks, and best practices.
Do not make changes directly - only provide recommendations.

---

Troubleshooting

Configuration Validation Errors

Error: Invalid input: expected record, received array provider.nexosai.models

This error occurs when the models field is defined as an array instead of an object. Each model must be a key-value pair where:

• The key is the model name (string)

• The value is an object (can be empty {} or contain optional properties like maxTokens)

Incorrect:

"models": ["Claude Opus 4.5", "gpt-4.1"]

Correct:

"models": {
  "Claude Opus 4.5": {},
  "gpt-4.1": {}
}

Error: Invalid input: expected record, received string provider

This error occurs when the provider field is a string instead of an object. The provider must be an object containing your provider configuration.

Error: Unrecognized key: "agents"

The correct field name is agent (singular), not agents (plural). For custom agents, use markdown files in the agents directory instead.

Base URL Issues

If you're getting connection errors, verify that the baseURL in your config matches includes full url (including /v1): https://api.nexos.ai/v1

Model Reference Format

Ensure your model references use the format provider-key/model-name (e.g., nexosai/Claude Opus 4.5).

---

Verification

To verify your nexos.ai integration is working:

1. Start OpenCode: opencode

2. Run the /models command to see available models

3. Press Tab to switch between Plan and Build agents

4. Try a simple prompt to confirm connectivity

You should see your configured nexos.ai models available and responses coming through the nexos.ai gateway, with all the benefits of load balancing, cost tracking, and observability that the platform provides.