OpenCode Setup Guide: Open-Source Claude Code Alternative on Your VPS

Claude Code is great. I use it. But it costs $20/month minimum, burns through your rate limits fast, and if you’re on the annual plan, you’re locked into Anthropic’s pricing. With GitHub Copilot switching to usage-based billing on June 1, a lot of developers are looking for something they can control.

OpenCode is the open-source alternative that keeps getting better. 120K+ GitHub stars, 75+ model providers, and you can run it on a $6/month VPS with open source models that cost pennies per request. I have been using it alongside Hermes Agent and OpenClaw for the past few weeks and it has become my default terminal coding agent.

This guide covers installation on a Linux VPS, connecting to cheap models, and the workflow I actually use day to day.

What OpenCode actually is

OpenCode is a terminal-based AI coding agent. It reads your codebase, plans changes, edits files, runs commands, and iterates on failures — the same loop Claude Code runs, but open source and provider-agnostic. It works with Anthropic, OpenAI, Google, Alibaba, MiniMax, DeepSeek, Xiaomi, Moonshot, and 70+ other providers. You can also use local models through Ollama.

The key difference from Claude Code: you pick the model and the provider. If Claude Sonnet is too expensive for a task, switch to Qwen 3.6 Plus at $0.33/M input tokens. If you need maximum reasoning, switch to GLM 5.1. You control the cost.

Installing OpenCode on a VPS

The install script handles everything. On a Linux VPS:

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

This installs the opencode binary. Verify it works:

opencode --version

Other install methods if the script does not work for your setup:

npm install -g opencode-ai

bun install -g opencode-ai

brew install anomalyco/tap/opencode

docker run -it --rm ghcr.io/anomalyco/opencode

What you need

• Node.js 18+ (the install script handles this on most systems)
• An API key from at least one provider
• A terminal emulator that supports images if you want drag-and-drop screenshots (WezTerm, Ghostty, Kitty, or Alacritty)

On a headless VPS, you don’t need the image support. OpenCode works fine over plain SSH.

Configuring a model provider

OpenCode supports three ways to connect models, from easiest to most flexible.

Option 1: OpenCode Zen (simplest)

OpenCode Zen is the built-in provider. You sign in at opencode.ai/auth, get an API key, and paste it into OpenCode. The Zen provider has a curated list of models tested and verified by the OpenCode team.

Run /connect in the TUI, select opencode, and paste your key.

Option 2: OpenRouter (most models)

OpenRouter gives you access to 200+ models through a single API key. This is what I use for most of my work.

# Add your OpenRouter key
echo "OPENROUTER_API_KEY=your-key-here" >> ~/.config/opencode/.env

Then in OpenCode, run /connect and select OpenRouter.

Option 3: Direct provider keys

For specific providers you can set environment variables directly:

# MiniMax
echo "MINIMAX_API_KEY=your-key" >> ~/.config/opencode/.env

# Z.AI (GLM)
echo "ZAI_API_KEY=your-key" >> ~/.config/opencode/.env

# Xiaomi MiMo
echo "MIMO_API_KEY=your-key" >> ~/.config/opencode/.env

# DeepSeek
echo "DEEPSEEK_API_KEY=your-key" >> ~/.config/opencode/.env

# Moonshot (Kimi)
echo "MOONSHOT_API_KEY=your-key" >> ~/.config/opencode/.env

OpenCode Go: $10/month, all models included

If you don’t want to manage multiple API keys, OpenCode Go bundles 12 popular open source models into a single subscription for $10/month. For a detailed breakdown of limits, model quality, and real-world usage, see the OpenCode Go guide.

What you get

• $10/month
• MiniMax M2.7, M2.5, MiMo V2.5 Pro, GLM 5, GLM 5.1, Kimi K2.5, K2.6, DeepSeek V4 Pro, V4 Flash, Qwen 3.5 Plus, Qwen 3.6 Plus, and more
• Models hosted in the US, EU, and Singapore
• Zero-retention policy

Usage limits

Cheaper models stretch further. MiniMax M2.7 gives you an estimated 3,400 requests per 5 hours. GLM 5.1 gives you 880.

Setting it up

Subscribe at opencode.ai/auth, copy your API key, then in OpenCode:

/connect

Select OpenCode Go and paste your key. Switch models with /models.

The Go endpoint is also accessible via API at https://opencode.ai/zen/go/v1/chat/completions, so you can use it with Hermes Agent or OpenClaw too.

Working with OpenCode day to day

Initialize a project

The first time you open OpenCode in a project:

cd /path/to/project
opencode

Then run:

/init

OpenCode analyzes your codebase and creates an AGENTS.md file in the project root. This file tells OpenCode about your project structure, coding patterns, and conventions. You can edit it manually to add custom instructions.

Plan mode vs build mode

This is the workflow I keep coming back to. Hit Tab to switch between modes:

Plan mode (read-only): OpenCode reads your codebase and describes how it would implement a feature. No changes are made. You review the plan, give feedback, iterate.

Build mode (read-write): OpenCode makes the actual changes to your files.

The pattern:

1. Switch to plan mode with Tab
2. Describe what you want
3. Review the plan, add constraints or images
4. Switch to build mode with Tab
5. Tell it to go ahead

This is safer than letting the agent loose immediately, especially on production code.

Referencing files

Use @ to point OpenCode at specific files:

Look at @src/api/auth.ts and add the same pattern to @src/api/settings.ts

Undo and redo

If OpenCode makes a change you don’t like:

/undo

It reverts the changes and shows your original prompt again so you can rephrase.

/redo

Brings the changes back if you changed your mind.

Sharing conversations

/share

Creates a link to your current conversation. Useful for showing teammates what the agent did or getting a second opinion on the plan.

Choosing the right model for the job

Not every task needs the most expensive model. Here is what I use:

Switch models in OpenCode with /models. No restart needed.

OpenCode vs Claude Code vs Codex CLI

The biggest advantage OpenCode has over Claude Code is model choice. You’re not locked into Anthropic’s pricing. When Claude Sonnet gets expensive, switch to a cheaper model for routine tasks and save Claude for the hard stuff.

The biggest advantage over Codex CLI is the plan mode and the ability to work with non-OpenAI models.

Running OpenCode on a VPS via SSH

OpenCode works over SSH. I run it on a $6/month Hetzner VPS and connect from my laptop. A few tips:

Use tmux so your session survives if the SSH connection drops:

tmux new -s code
cd /path/to/project
opencode

If you detach (Ctrl+B, D) and reconnect later, tmux attach -t code puts you back where you left off.

For a better terminal experience over SSH, use mosh instead of plain SSH. It handles network drops and roaming better:

mosh user@your-vps-ip

FAQ

If you are also running AI agents on your server, check out our Hermes Agent setup guide and OpenClaw alternatives roundup. For the cheapest models to use with any of these tools, the best cheap models for Hermes Agent guide covers pricing and benchmarks. For Alibaba’s latest Qwen 3.6 models that work great with OpenCode, see the Qwen 3.6 for AI coding agents guide. If you want a more minimal terminal coding agent with a TypeScript extension system, our Pi coding agent setup guide covers installation, model configuration, and the best extensions. For a detailed comparison of these two agents, see the OpenCode vs Pi Agent comparison. For a deep dive into OpenCode Go’s limits, models, and whether the subscription is worth it, see the OpenCode Go guide.