---
title: "OpenCode Setup Guide: Open-Source Claude Code Alternative on Your VPS"
description: "Install and configure OpenCode on a Linux VPS. Connect it to cheap open source models like MiniMax M2.7, Qwen 3.6, and DeepSeek V4. The open-source alternative to Claude Code that costs a fraction of the price."
date: 2026-04-30
categories: ["AI"]
tags: ["ai-tools","self-hosted","vps"]
---
import Button from "@components/widgets/Button.astro";
import Notice from "@components/widgets/Notice.astro";
import ListCheck from "@components/widgets/ListCheck.astro";
import Accordion from "@components/widgets/Accordion.astro";
import Tabs from "@components/widgets/Tabs.astro";
import Tab from "@components/widgets/Tab.astro";
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](/github-copilot-alternatives-2026/), a lot of developers are looking for something they can control.
[OpenCode](https://opencode.ai/) 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](/hermes-agent-setup-guide/) and [OpenClaw](/clawdbot-setup-guide/) 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.
Installing OpenCode on a Linux VPS in under a minute
Connecting to cheap open source models via OpenRouter and direct providers
Setting up OpenCode Go for $10/month with access to 12 models
Plan mode vs build mode, the /init workflow, and real usage tips
How OpenCode compares to Claude Code, Codex CLI, and Aider
## 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:
```bash
curl -fsSL https://opencode.ai/install | bash
```
This installs the `opencode` binary. Verify it works:
```bash
opencode --version
```
Other install methods if the script does not work for your setup:
```bash
npm install -g opencode-ai
```
```bash
bun install -g opencode-ai
```
```bash
brew install anomalyco/tap/opencode
```
```bash
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](https://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.
```bash
# 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:
```bash
# 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](https://go.bitdoze.com/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](/opencode-go-plan/).
### 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
| Limit | Cap |
|-------|-----|
| Per 5 hours | $12 |
| Per week | $30 |
| Per month | $60 |
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](https://go.bitdoze.com/opencode-go), 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](/hermes-agent-setup-guide/) or [OpenClaw](/clawdbot-setup-guide/) too.
## Working with OpenCode day to day
### Initialize a project
The first time you open OpenCode in a project:
```bash
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:
| Task | Model | Why |
|------|-------|-----|
| Quick edits, file refactoring | MiniMax M2.7 | Cheap and fast, handles most edits fine |
| Frontend work, UI generation | Qwen 3.6 Plus | Strong at "vibe coding" and design |
| Complex multi-file changes | GLM 5.1 | Best coding accuracy, worth the cost |
| Long context, big repos | DeepSeek V4 Pro | 1M context, low hallucination rate |
| Default everyday use | MiniMax M2.7 or Qwen 3.6 Plus | Balance of cost and quality |
Switch models in OpenCode with `/models`. No restart needed.
## OpenCode vs Claude Code vs Codex CLI
| Feature | OpenCode | Claude Code | Codex CLI |
|---------|----------|-------------|-----------|
| **Price** | Free (pay for API) | $20/month + API | Included with ChatGPT |
| **Model choice** | 75+ providers | Anthropic only | OpenAI only |
| **Open source** | Yes | No | Yes |
| **Plan mode** | Yes (Tab key) | No (use /plan) | No |
| **Image support** | Drag and drop | Paste images | No |
| **MCP servers** | Yes | Yes | Yes |
| **Undo/redo** | /undo, /redo | Git-based | No |
| **VPS friendly** | Yes | Yes | Yes |
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.
Using your Claude Code or ChatGPT subscription OAuth tokens with automated coding agents can get your account banned. These providers monitor for automated usage. Use API keys from the models listed above instead. See our [models guide](/best-opensource-models-for-openclaw/) for the full breakdown.
## 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:
```bash
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:
```bash
mosh user@your-vps-ip
```
## FAQ
The software is free and open source. You pay for the LLM API usage. If you use OpenCode Go, that's $5 for the first month then $10/month. If you use direct provider keys, you pay per token. MiniMax M2.7 through OpenRouter costs $0.30/M input tokens, which is roughly $3-7/month for typical coding use.
Yes. Set `OPENAI_BASE_URL=http://localhost:11434/v1` and `OPENAI_API_KEY=ollama` in your OpenCode config. Then select the local model in OpenCode. See our [Ollama Docker guide](/ollama-docker-install/) for setting up Ollama. Performance depends on your hardware — a 7B model handles simple edits, but complex multi-file tasks need at least a 32B model.
Both are terminal coding agents. OpenCode has a richer TUI with plan mode, image support, and sharing. Aider is more minimal and has stronger git integration. Aider supports more obscure model providers. For most developers, OpenCode is the better daily driver.
Yes, they complement each other. OpenCode is for coding tasks — editing files, running builds, fixing bugs. Hermes Agent is for broader tasks — web searches, scheduled jobs, messaging, server management. Run both on the same VPS.
Any Linux VPS with 1GB+ RAM works. OpenCode itself is lightweight — the heavy lifting happens at the API provider. A $6/month Hetzner CX22 or equivalent is more than enough. See our [VPS hosting comparison](/vps-ai-coding-setup/) for options.
If you are also running AI agents on your server, check out our [Hermes Agent setup guide](/hermes-agent-setup-guide/) and [OpenClaw alternatives](/openclaw-alternatives/) roundup. For the cheapest models to use with any of these tools, the [best cheap models for Hermes Agent](/best-cheap-models-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](/qwen36-ai-coding-agents/) guide. If you want a more minimal terminal coding agent with a TypeScript extension system, our [Pi coding agent setup guide](/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](/opencode-vs-pi-agent/). For a deep dive into OpenCode Go's limits, models, and whether the subscription is worth it, see the [OpenCode Go guide](/opencode-go-plan/).