Configure OpenCode

OpenCode ↗ is an open-source AI coding agent available in the terminal, desktop app, and IDE extensions. This guide connects OpenCode to LAYSO AI through its official custom-provider workflow.

One key for all platform models

Models are billed at the current prices shown on LAYSO AI Models & Pricing. Every successful request has an itemized charge; failed tasks are not charged.

Setup

Step 1: Install OpenCode

macOS / Linux / WSL

Use the official installer:

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

You can also use npm or Homebrew:

npm install -g opencode-ai
# or
brew install anomalyco/tap/opencode

Windows

OpenCode recommends WSL on Windows. You can also install through npm, Chocolatey, or Scoop:

npm install -g opencode-ai
# or
choco install opencode
# or
scoop install opencode

Verify the installation

opencode --version

A version number confirms that installation succeeded.

Step 2: Get an API key and model ID

1. Create and copy a key from LAYSO AI API Keys ↗.
2. Choose a model on LAYSO AI Models & Pricing ↗ and copy the exact model ID shown there.

One LAYSO AI API key can access platform models. Do not guess model aliases or place a real key in a project file or Git repository.

Step 3: Store the API key

Start OpenCode:

opencode

Enter this command in the TUI:

/connect

Complete these steps:

1. Select Other at the bottom of the provider list.
2. Enter layso_ai as the provider ID.
3. Paste the full key from the LAYSO AI API Key page.

/connect stores only the credential. You still need to define the provider and model in opencode.json in the next step. The provider ID must exactly match layso_ai in the configuration.

Why use /connect?

OpenCode manages its credential store, so a real key does not need to appear in opencode.json. Run /connect again to replace or remove the saved credential.

Step 4: Open the global configuration

The global configuration applies to every project for the current user:

System	Configuration file
macOS	/Users/<username>/.config/opencode/opencode.json
Windows	C:\Users\<username>\.config\opencode\opencode.json
Linux / WSL	/home/<username>/.config/opencode/opencode.json

Create the directory on macOS, Linux, or WSL:

mkdir -p ~/.config/opencode

On Windows PowerShell:

New-Item -ItemType Directory -Force "$HOME\.config\opencode"
notepad "$HOME\.config\opencode\opencode.json"

If the project root also contains opencode.json, project values override matching global values. Check both locations while troubleshooting.

Step 5: Configure the LAYSO AI provider

Replace <MODEL_ID> with an exact ID from Models & Pricing:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "layso_ai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LAYSO AI",
      "options": {
        "baseURL": "https://api.layso.ai/v1"
      },
      "models": {
        "<MODEL_ID>": {
          "name": "LAYSO AI Model"
        }
      }
    }
  },
  "model": "layso_ai/<MODEL_ID>"
}

This uses OpenAI Chat Completions compatibility for LAYSO AI /v1/chat/completions. The fields mean:

Field	Purpose	LAYSO AI value
layso_ai	Custom provider ID	Must match the ID entered through /connect
npm	OpenCode protocol adapter	@ai-sdk/openai-compatible
name	Provider name in the model picker	LAYSO AI
options.baseURL	OpenAI-compatible base URL	https://api.layso.ai/v1
models	Models visible to OpenCode	Exact IDs from the pricing page
model	Default model	layso_ai/<MODEL_ID>

Step 6: Verify the configuration

Confirm that OpenCode recognizes the provider and models:

opencode models layso_ai

Then run a non-interactive test:

opencode run --model "layso_ai/<MODEL_ID>" "Introduce yourself in one sentence"

You can also start the TUI:

opencode

Enter /models, select a model under LAYSO AI, and send a short task. After it succeeds, verify the model, tokens, and charge in LAYSO AI task details.

Add multiple models

A provider can register multiple models. The following example configures primary and fast roles:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "layso_ai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LAYSO AI",
      "options": {
        "baseURL": "https://api.layso.ai/v1"
      },
      "models": {
        "<PRIMARY_MODEL_ID>": {
          "name": "LAYSO AI Primary"
        },
        "<FAST_MODEL_ID>": {
          "name": "LAYSO AI Fast"
        }
      }
    }
  },
  "model": "layso_ai/<PRIMARY_MODEL_ID>",
  "small_model": "layso_ai/<FAST_MODEL_ID>"
}

model is the default primary model, while small_model handles lightweight work such as title generation. Both values use provider ID/model ID.

Use an environment variable for the key

If you do not want /connect to store the credential, read the key from an environment variable instead:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "layso_ai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LAYSO AI",
      "options": {
        "baseURL": "https://api.layso.ai/v1",
        "apiKey": "{env:LAYSO_API_KEY}"
      },
      "models": {
        "<MODEL_ID>": {
          "name": "LAYSO AI Model"
        }
      }
    }
  },
  "model": "layso_ai/<MODEL_ID>"
}

macOS / Linux / WSL

export LAYSO_API_KEY="sk-..."
opencode

Windows PowerShell

$env:LAYSO_API_KEY = "sk-..."
opencode

These variables apply only to the current terminal session. For persistent use, store them in a user-level secure environment configuration, never in a project .env committed to the repository.

Responses API configuration

If a selected model or feature explicitly requires the OpenAI Responses API, use @ai-sdk/openai; the base URL remains https://api.layso.ai/v1:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "layso_responses": {
      "npm": "@ai-sdk/openai",
      "name": "LAYSO AI Responses",
      "options": {
        "baseURL": "https://api.layso.ai/v1",
        "apiKey": "{env:LAYSO_API_KEY}"
      },
      "models": {
        "<MODEL_ID>": {
          "name": "LAYSO AI Responses Model"
        }
      }
    }
  },
  "model": "layso_responses/<MODEL_ID>"
}

When using /connect, enter layso_responses as the provider ID as well. If you are unsure which protocol is required, start with the OpenAI-compatible configuration above.

Project-level configuration

To pin a model for one project, add opencode.json at the project root:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "layso_ai/<MODEL_ID>"
}

Project configuration merges with the global configuration, so the provider and key do not need to be repeated. Never place a real API key in project configuration.

Recommended models

Use LAYSO AI Models & Pricing ↗ as the source of truth. Prioritize:

Workflow	Prioritize
Everyday code edits	latency, tool use, price
Large repository analysis	context length, code understanding
Complex refactors and debugging	reasoning, reliable tool use
Frequent lightweight tasks	low latency, low price

Do not copy aliases from another platform. The model ID in OpenCode must exactly match the ID shown on LAYSO AI.

Common commands

Command	Purpose
opencode	Start the terminal UI
/connect	Add, replace, or remove provider credentials
/models	Select a model in the TUI
/init	Create or update AGENTS.md for the current project
opencode models layso_ai	List models under the LAYSO AI provider
opencode run "task"	Run one non-interactive task

Authentication and troubleshooting

401 / 403 authentication errors

• Run /connect again and confirm that the provider ID is layso_ai.
• Paste the complete key again and check for spaces, line breaks, or missing characters.
• When using an environment variable, make sure the terminal launching OpenCode can read LAYSO_API_KEY.

404 or incorrect request URL

Confirm that options.baseURL is https://api.layso.ai/v1. Do not append another /v1 or use a complete /chat/completions or /responses endpoint here.

Provider or model is missing

1. Confirm that the global filename is opencode.json or opencode.jsonc.
2. Use provider, not providers or the TOML format found in older tutorials.
3. Confirm that models is an object keyed by model ID.
4. Check whether a project-root opencode.json overrides the global configuration.
5. Run opencode models layso_ai --refresh to refresh the list.

Model not found

Confirm that these values match exactly:

1. The model key under provider.layso_ai.models.
2. The <MODEL_ID> portion of layso_ai/<MODEL_ID>.
3. The exact ID shown on LAYSO AI Models & Pricing.

Tool calls fail

Choose a model explicitly marked as supporting tool calls on the pricing page, then retry with a short task. Tool use, image input, and context capabilities differ by model.

Billing and security

• One LAYSO AI API key can access all platform models.
• Every successful request shows its model, tokens, and itemized charge in task details.
• Failed tasks are not charged.
• Never expose a full API key in screenshots, logs, project configuration, or Git.