Skip to main content

Installing OpenCode

OpenCode is the reference implementation of the Marea pattern - a CLI tool that connects AI models to your files and system tools.

Prerequisites​

Before installing OpenCode, you'll need:

  • Node.js version 20.0 or above
  • pnpm (recommended) or npm
  • An AI model API key (Claude, OpenAI, etc.)

Installing Node.js​

Download and install from nodejs.org

Verify installation:

node --version  # Should be v20.0.0 or higher
npm install -g pnpm

Installation​

npm install -g opencode

Or with pnpm:

pnpm add -g opencode

Verify installation:

opencode --version

Option 2: Build from source​

Clone the repository:

git clone https://github.com/marea-dev/opencode.git
cd opencode
pnpm install
pnpm build
pnpm link --global

Configuration​

1. Set up your API keys​

OpenCode supports multiple AI providers. Configure at least one:

Claude (Anthropic)​

export ANTHROPIC_API_KEY="your-api-key-here"

Get your API key from console.anthropic.com

OpenAI (GPT models)​

export OPENAI_API_KEY="your-api-key-here"

Get your API key from platform.openai.com

Google AI (Gemini)​

export GOOGLE_API_KEY="your-api-key-here"

Get your API key from ai.google.dev

tip

Add these to your shell profile (~/.zshrc or ~/.bashrc) to persist across sessions:

# Add to ~/.zshrc (macOS/Linux)
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc

2. Initialize OpenCode​

Create your configuration directory:

opencode init

This creates:

~/.opencode/
  config.json       # OpenCode settings
  context/          # Your context files
  tools/            # Custom tool definitions
  prompts/          # Reusable prompts

3. Configure your default model​

Edit ~/.opencode/config.json:

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-3-5-haiku-20241022",
  "contextDir": "~/.opencode/context",
  "toolsDir": "~/.opencode/tools"
}

Recommended models:

  • Claude Haiku 3.5 - Fast, cheap, reliable tool calling
  • Claude Sonnet 3.5 - More capable, higher cost
  • GPT-4o - OpenAI's best for tool calling
  • Gemini 1.5 Pro - Good balance of speed and capability

Verify Installation​

Test that OpenCode is working:

opencode "What's 2+2?"

You should see:

4

Test tool calling:

opencode "List files in the current directory"

OpenCode should invoke the ls command and show results.

Next Steps​

Troubleshooting​

"command not found: opencode"​

Make sure your global npm/pnpm bin is in your PATH:

# For npm
export PATH="$PATH:$(npm bin -g)"

# For pnpm
export PATH="$PATH:$(pnpm bin -g)"

"API key not found"​

Ensure your environment variable is set:

echo $ANTHROPIC_API_KEY  # Should print your key

If empty, set it in your shell profile and restart your terminal.

Permission errors on Linux/macOS​

If you see permission errors during install:

sudo chown -R $USER /usr/local/lib/node_modules

Or use nvm to manage Node.js without sudo.