Integration: OpenCode with Lunos

This guide shows how to configure OpenCode to use Lunos as your AI provider so you can run coding workflows powered by Lunos models directly from your terminal.

What is OpenCode?

OpenCode is a terminal-based AI coding assistant that runs in your shell. It supports multiple providers through the AI SDK ecosystem and can be extended with subagents for tasks like codebase exploration. Configuration is done via a single JSONC file.

Prerequisites

• OpenCode installed on your machine (opencode.ai)
• Lunos API key (get one from your dashboard)
• Lunos base URL: https://api.lunos.tech/v1

Setup

1) Install OpenCode

macOS / Linux

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

Windows (PowerShell)

irm https://opencode.ai/install.ps1 | iex

Check the OpenCode docs for alternative installation methods (Homebrew, Scoop, etc.) if available.

2) Create the configuration file

OpenCode reads its config from .config/opencode/opencode.jsonc relative to your home directory.

macOS / Linux

Create the config directory and file:

mkdir -p ~/.config/opencode

Then create ~/.config/opencode/opencode.jsonc with the following content:

Windows

Create the config directory:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode"

Then create %USERPROFILE%\.config\opencode\opencode.jsonc with the following content:

3) Add the Lunos provider configuration

Paste this into your opencode.jsonc file:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lunos": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.lunos.tech/v1",
        "apiKey": "your-lunos-api-key"
      },
      "models": {
        "deepseek/deepseek-v4-flash": {
          "name": "deepseek/deepseek-v4-flash"
        }
      }
    }
  },
  "model": "lunos/deepseek/deepseek-v4-flash",
  "agent": {
    "explorer": {
      "description": "Fast explorer subagent for codebase exploration",
      "mode": "subagent",
      "model": "lunos/deepseek/deepseek-v4-flash"
    }
  }
}

Replace "your-lunos-api-key" with your actual Lunos API key.

4) Add more models (optional)

You can register multiple Lunos models under the same provider:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lunos": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.lunos.tech/v1",
        "apiKey": "your-lunos-api-key"
      },
      "models": {
        "deepseek/deepseek-v4-flash": {
          "name": "deepseek/deepseek-v4-flash"
        },
        "anthropic/claude-sonnet-4-20250514": {
          "name": "anthropic/claude-sonnet-4-20250514"
        },
        "openai/gpt-4o": {
          "name": "openai/gpt-4o"
        }
      }
    }
  },
  "model": "lunos/deepseek/deepseek-v4-flash",
  "agent": {
    "explorer": {
      "description": "Fast explorer subagent for codebase exploration",
      "mode": "subagent",
      "model": "lunos/deepseek/deepseek-v4-flash"
    }
  }
}

5) Run OpenCode

From your project directory:

opencode

OpenCode will use the Lunos provider and model specified in your config.

Configuration reference

Field	Description
provider.lunos.npm	The AI SDK package for OpenAI-compatible providers
provider.lunos.options.baseURL	Lunos API endpoint (https://api.lunos.tech/v1)
provider.lunos.options.apiKey	Your Lunos API key
provider.lunos.models	Map of model IDs available through this provider
model	Default model in provider/model-id format
agent.explorer	Subagent config for codebase exploration tasks

Switching models

To change the active model, update the "model" field in your config:

"model": "lunos/anthropic/claude-sonnet-4-20250514"

The format is provider-name/model-id — where provider-name matches the key you defined under "provider" (in this case lunos).

Subagents

OpenCode supports subagents for delegating specific tasks. The example config includes an explorer subagent for fast codebase navigation. You can add more subagents following the same pattern:

"agent": {
  "explorer": {
    "description": "Fast explorer subagent for codebase exploration",
    "mode": "subagent",
    "model": "lunos/deepseek/deepseek-v4-flash"
  },
  "reviewer": {
    "description": "Code review subagent",
    "mode": "subagent",
    "model": "lunos/anthropic/claude-sonnet-4-20250514"
  }
}

Troubleshooting

Auth errors (401/403)

• Verify the API key is correct and active in your dashboard.
• Ensure the key has not been revoked or expired.

Model not found

• Confirm the model ID matches exactly with a model available in your Lunos models list.
• Model IDs are case-sensitive.
• The "model" field must use the format lunos/model-id (provider prefix + model ID).

Config not loading

• Ensure the file is at the correct path:
  • Linux/macOS: ~/.config/opencode/opencode.jsonc
  • Windows: %USERPROFILE%\.config\opencode\opencode.jsonc
• Validate the JSONC syntax (trailing commas and comments are allowed, but check for typos).

Connection timeout or network errors

• Confirm the base URL is https://api.lunos.tech/v1 (with the /v1 suffix).
• Check that your network allows outbound HTTPS connections.

Security

• Never commit API keys into repositories.
• Use per-project or per-environment API keys when possible.
• Add opencode.jsonc to your global .gitignore if it contains secrets:

# Linux/macOS
echo ".config/opencode/opencode.jsonc" >> ~/.gitignore_global

# Windows (PowerShell)
Add-Content "$env:USERPROFILE\.gitignore_global" ".config/opencode/opencode.jsonc"