Open Code Configuration

OpenCode uses JSON configuration format and supports both system-level (global) and project-level (local) configuration.

Configuration Files

System-Level Configuration

Location: ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:EMBY_API_KEY}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  },
  "autoupdate": true,
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}

The CLI fetches available models from Emby and adds them to the provider.anthropic.models section automatically.

Project-Level Configuration

Location: ./opencode.json (in project root)

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:EMBY_API_KEY}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  },
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}

Use project-level configuration to customize settings per project while keeping a global default. The {env:EMBY_API_KEY} syntax references the environment variable.

Manual Setup

System-Level Manual Setup

# 1. Create directory
mkdir -p ~/.config/opencode

# 2. Create config file
cat > ~/.config/opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:EMBY_API_KEY}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  },
  "autoupdate": true,
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}
EOF

# 3. Set environment variable
echo 'export EMBY_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

# 4. Verify
cat ~/.config/opencode/opencode.json | jq .

Project-Level Manual Setup

# 1. Navigate to project
cd ~/projects/my-project

# 2. Create config file
cat > opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:EMBY_API_KEY}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  },
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}
EOF

# 3. Set environment variable (if not already set)
echo 'export EMBY_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

# 4. Add to .gitignore
echo "opencode.json" >> .gitignore

Configuration Priority

OpenCode loads configuration in this order (highest to lowest priority):

Environment Variables

EMBY_API_KEY environment variable (referenced via {env:EMBY_API_KEY} in config)

Project-Level Config

./opencode.json in current directory

System-Level Config

~/.config/opencode/opencode.json in home directory

Configuration Options

Provider Settings

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "models": {
        "gpt-5": {
          "id": "gpt-5",
          "name": "GPT-5 (Via Emby)"
        },
        "claude-4.5-sonnet": {
          "id": "claude-4.5-sonnet",
          "name": "Claude Sonnet 4.5"
        }
      },
      "options": {
        "apiKey": "{env:EMBY_API_KEY}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  }
}

The CLI automatically fetches and populates the models object from the Emby API. You can also manually add or override specific models.

Tool Settings

{
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  },
  "autoupdate": true
}

Available models:

gpt-5 - Latest GPT model
gpt-4 - GPT-4
claude-opus-4-1-20250805 - Claude Opus
claude-sonnet-4.5 - Claude Sonnet
gemini-3.0-pro - Gemini Pro
See Models Catalog for full list

Complete Example

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "models": {
        "gpt-5": {
          "id": "gpt-5",
          "name": "GPT-5 (Via Emby)"
        },
        "gpt-4": {
          "id": "gpt-4",
          "name": "GPT-4 (Via Emby)"
        },
        "claude-sonnet-4": {
          "id": "claude-sonnet-4",
          "name": "Claude Sonnet 4 (Via Emby)"
        }
      },
      "options": {
        "apiKey": "{env:EMBY_API_KEY}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  },
  "autoupdate": true,
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}

Team Configuration

For team projects, use environment variables to keep API keys out of version control: Shared Configuration (opencode.json - committed to git):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:EMBY_API_KEY}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  },
  "autoupdate": true,
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}

Add to .gitignore:

opencode.json

Setup Instructions for Team (README.md):

# OpenCode Setup

## Prerequisites

1. Get Emby API key from https://dev.emby.ai/home
2. Install OpenCode: `npm install -g opencode-ai`

## Setup

Set the EMBY_API_KEY environment variable:

```bash
export EMBY_API_KEY="your-api-key-here"
```

Add to your shell config (~/.bashrc or ~/.zshrc) to make it permanent.

## Environment Variables

```bash
export EMBY_API_KEY="sk-emby-your-api-key-here"
```

This environment variable is referenced in the OpenCode configuration using `{env:EMBY_API_KEY}`.

Add to your shell configuration:

```bash  theme={null}
# ~/.bashrc or ~/.zshrc
export EMBY_API_KEY="sk-emby-your-api-key-here"
```

### Verify Environment Variables

```bash  theme={null}
echo $EMBY_API_KEY
# Output: sk-emby-your-api-key-here
```

## Verification

### Check Configuration Files

```bash  theme={null}
# System config
cat ~/.config/opencode/opencode.json | jq .

# Project config
cat opencode.json | jq .
cat opencode.local.json | jq .

# Check file permissions
ls -la ~/.config/opencode/opencode.json
ls -la opencode.json
```

### Validate JSON Syntax

```bash  theme={null}
# Validate JSON
jq . ~/.config/opencode/opencode.json

# Should show formatted JSON or error if invalid
```

### Test API Connection

```bash  theme={null}
# Test with EMBY_API_KEY
curl -H "Authorization: Bearer $EMBY_API_KEY" \
     -H "Content-Type: application/json" \
     https://dev.emby.ai/v1/models

# Should return list of available models
```

### Test OpenCode

```bash  theme={null}
# Run OpenCode
opencode

# Check version
opencode --version

# Test with a file
echo "console.log('test')" > test.js
opencode test.js
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Configuration not loading">
    **Check file locations:**

    ```bash  theme={null}
    # System config
    ls -la ~/.config/opencode/opencode.json

    # Project config
    ls -la opencode.json
    ```

    **Validate JSON syntax:**

    ```bash  theme={null}
    jq . ~/.config/opencode/opencode.json
    # Should show formatted JSON
    ```

    **Check you're in the right directory:**

    ```bash  theme={null}
    pwd
    # Should be your project directory for project-level config
    ```
  </Accordion>

  <Accordion title="API key not recognized">
    **Check environment variable:**

    ```bash  theme={null}
    echo $EMBY_API_KEY
    ```

    If empty, set it:

    ```bash  theme={null}
    export EMBY_API_KEY="your-api-key"
    echo 'export EMBY_API_KEY="your-api-key"' >> ~/.bashrc
    source ~/.bashrc
    ```

    **Verify key format:**

    * Must start with `sk-emby-`
    * At least 20 characters
    * No extra spaces or quotes

    **Test the key:**

    ```bash  theme={null}
    curl -H "Authorization: Bearer $EMBY_API_KEY" \
         -H "Content-Type: application/json" \
         https://dev.emby.ai/v1/models
    ```
  </Accordion>

  <Accordion title="Wrong base URL">
    **Check config:**

    ```bash  theme={null}
    jq '.provider.anthropic.options.baseURL' ~/.config/opencode/opencode.json
    # Should show: "https://dev.emby.ai/v1"
    ```

    **Common mistakes:**

    ```json  theme={null}
    {
      "provider": {
        "anthropic": {
          "options": {
            "baseURL": "https://dev.emby.ai/v1"  // ✓ Correct
            // "baseURL": "https://dev.emby.ai/v1/"  // ✗ Wrong (trailing slash)
            // "baseURL": "https://dev.emby.ai"  // ✗ Wrong (missing /v1)
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Project config not overriding system config">
    **Verify you have project config:**

    ```bash  theme={null}
    ls -la opencode.json
    ```

    **Ensure proper JSON structure:**
    Project config should use the same structure as system config with `provider.anthropic.options`.
  </Accordion>

  <Accordion title="JSON syntax errors">
    **Common JSON mistakes:**

    ```json  theme={null}
    // ✗ Wrong - trailing comma
    {
      "provider": {
        "anthropic": {
          "options": {
            "apiKey": "{env:EMBY_API_KEY}",
          }
        }
      }
    }

    // ✓ Correct
    {
      "provider": {
        "anthropic": {
          "options": {
            "apiKey": "{env:EMBY_API_KEY}"
          }
        }
      }
    }

    // ✗ Wrong - single quotes
    {
      'provider': {
        'anthropic': {
          'options': {
            'apiKey': '{env:EMBY_API_KEY}'
          }
        }
      }
    }

    // ✓ Correct - double quotes
    {
      "provider": {
        "anthropic": {
          "options": {
            "apiKey": "{env:EMBY_API_KEY}"
          }
        }
      }
    }
    ```

    **Validate:**

    ```bash  theme={null}
    jq . ~/.config/opencode/opencode.json
    # Will show error if invalid
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Local Config for API Keys" icon="key">
    Keep API keys in `opencode.local.json` and add to `.gitignore`
  </Card>

  <Card title="Share Base Config" icon="users">
    Commit `opencode.json` without API keys for team consistency
  </Card>

  <Card title="Project-Specific Settings" icon="folder">
    Use project-level config for project-specific context and settings
  </Card>

  <Card title="Validate JSON" icon="check">
    Always validate JSON syntax after manual edits
  </Card>
</CardGroup>

## Advanced Usage

### Multiple Profiles

```bash  theme={null}
# Create different profiles
cat > ~/.config/opencode/opencode.dev.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:EMBY_API_KEY_DEV}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  }
}
EOF

cat > ~/.config/opencode/opencode.prod.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:EMBY_API_KEY_PROD}",
        "baseURL": "https://dev.emby.ai/v1"
      }
    }
  }
}
EOF

# Set environment variables
export EMBY_API_KEY_DEV="sk-emby-dev-key"
export EMBY_API_KEY_PROD="sk-emby-prod-key"

# Switch profiles
alias opencode-dev='cp ~/.config/opencode/opencode.dev.json ~/.config/opencode/opencode.json && opencode'
alias opencode-prod='cp ~/.config/opencode/opencode.prod.json ~/.config/opencode/opencode.json && opencode'
```

### CI/CD Configuration

```yaml  theme={null}
# GitHub Actions example
- name: Configure OpenCode
  env:
    EMBY_API_KEY: ${{ secrets.EMBY_API_KEY }}
  run: |
    mkdir -p ~/.config/opencode
    cat > ~/.config/opencode/opencode.json << 'EOF'
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "anthropic": {
          "options": {
            "apiKey": "{env:EMBY_API_KEY}",
            "baseURL": "https://dev.emby.ai/v1"
          }
        }
      }
    }
    EOF
```


**For the latest documentation, please visit:** [https://opencode.ai/docs/providers/](https://opencode.ai/docs/providers/)

IDE Integrations

Workflow Automation

Cloud Providers

Configuration Files

System-Level Configuration

Project-Level Configuration

Manual Setup

System-Level Manual Setup

Project-Level Manual Setup

Configuration Priority

Configuration Options

Provider Settings

Tool Settings

Complete Example

Team Configuration

IDE Integrations

Workflow Automation

Cloud Providers

​Configuration Files

​System-Level Configuration

​Project-Level Configuration

​Manual Setup

​System-Level Manual Setup

​Project-Level Manual Setup

​Configuration Priority

​Configuration Options

​Provider Settings

​Tool Settings

​Complete Example

​Team Configuration

Configuration Files

System-Level Configuration

Project-Level Configuration

Manual Setup

System-Level Manual Setup

Project-Level Manual Setup

Configuration Priority

Configuration Options

Provider Settings

Tool Settings

Complete Example

Team Configuration