Run OpenCode on a VPS

What OpenCode is, and what you are setting up

OpenCode is an open source AI coding agent built for the terminal. You start it inside a project directory, and it reads your code, proposes changes, edits files, and runs commands, all from a terminal user interface (TUI). It is MIT licensed, it connects to more than 75 model providers, and with roughly 165,000 GitHub stars as of mid-2026 it is the most-starred open source coding agent there is. To run OpenCode on a VPS, you install it under a dedicated unprivileged user, put your model API key in a private file, and start it inside tmux so the session survives when your connection drops. This guide does exactly that, in that order.

One naming note saves confusion. The canonical repository is anomalyco/opencode, maintained by the Anomaly team (previously known as SST), and the project used to live at sst/opencode. An older, unrelated repository named opencode-ai/opencode also exists on GitHub, so check that you are reading the right project's docs. The official site is opencode.ai.

Why run OpenCode on a VPS

A coding agent session is long. OpenCode can spend many minutes working through a refactor or a test suite, and if it runs on your laptop, a closed lid or a dropped Wi-Fi connection kills the session mid-task. On a VPS inside tmux, the agent keeps working after you disconnect, and you reattach later to read what it did. This is the same pattern as running Claude Code on a VPS with tmux, and it is the single biggest quality-of-life gain of moving an agent off your laptop.

The second reason is placement. A VPS is close to the code you deploy: the repository, the build tools, the test database, and often the staging environment already live there or next to it. An agent that edits code and runs the tests works best on the machine where those tests actually run. And because the box is a server you control, you can give the agent a contained environment on purpose, which the next section does.

If you are still choosing a tool, running a coding AI agent on a VPS compares the wider field, including Aider and Goose.

Give OpenCode its own user

Here is the honest starting point: a coding agent edits files and runs commands. That is its job, and it is also the risk. OpenCode will run builds, tests, and whatever shell commands the task seems to need, and the model's judgement is good but not perfect. The account the agent runs as is the ceiling on what a bad command can reach, so do not run it as root, and do not run it as the same user that administers the server.

Unlike a background agent, OpenCode is interactive, so its user needs a real shell and a home directory:

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

Keep the projects you want it to work on under /home/opencode, cloned by that user. Give the account no sudo rights. If the agent runs a destructive command, it can only destroy what this one account owns, which is the same reasoning as running services as an unprivileged user. Work inside a git repository as well, because a repository turns any bad edit into a git revert instead of a loss.

Install OpenCode

The project documents two installs. The install script is the quickest, and running it as the opencode user keeps everything inside that user's home:

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

The usual curl | bash habit applies here as it does everywhere: on a server you care about, download the script first, read it, then run it. After the install, start a new shell so the PATH change the installer makes takes effect, then check the binary answers:

opencode --version

If you prefer a package manager and Node.js is already on the box, the npm route installs the same tool system-wide, which puts the opencode binary on the PATH for every user:

sudo npm install -g opencode-ai

Either way, the check is the same: opencode --version prints a version number. A command not found after the script install means the current shell has not read the updated PATH yet, so log out and back in as the opencode user.

Put the API key in a private file

OpenCode needs a key for whatever model provider you use, and that key can spend your money, so treat it like a password. Create a file only the opencode user can read, with mode 600, and keep the key there instead of typing it into commands where it would land in your shell history:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

Put your provider's variable in it, for example ANTHROPIC_API_KEY=... or the equivalent for your provider, because OpenCode picks up the standard provider environment variables. Load the file into your shell before you start the agent:

set -a; source ~/opencode.env; set +a

OpenCode also has an interactive alternative: the /connect command inside the TUI walks you through adding a provider and saves the credential to ~/.local/share/opencode/auth.json in the user's home. If you use that route, confirm the file is private with chmod 600 ~/.local/share/opencode/auth.json. Both routes keep the key out of your command lines; pick one and stay consistent.

Start OpenCode inside tmux

tmux is what makes the VPS setup worth it, because a tmux session keeps running when your SSH connection ends. Start one, move into your project, and launch the agent:

tmux new -s opencode
cd ~/my-project
opencode

You should see the TUI open with a prompt at the bottom and your project name in the interface. Give it a task in plain language, and it starts reading files and proposing changes. When you want to leave, detach with Ctrl-b then d, and the agent keeps working with your laptop closed. Reattach later with:

tmux attach -t opencode

The session, the conversation, and any running task are exactly where you left them. This survives your disconnections, but not a server reboot, so after a reboot you start a fresh tmux session the same way.

Point it at a model

OpenCode is provider agnostic. It uses the AI SDK and the Models.dev catalog to support more than 75 providers, so the same tool works with Anthropic, OpenAI, Google, and dozens of others, including local servers. The quick route is the /connect command inside the TUI, which lists providers and handles the credential. For a setup you can commit and reproduce, put an opencode.json in the project root and set the model as provider/model-id:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

A local model works through the same file, because any OpenAI-compatible server can be declared as a provider. If you serve a model with Ollama on the same VPS, the config points at its local API, and the model name is whatever ollama list shows on your box:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

One built-in habit is worth adopting from day one. OpenCode ships two agents you switch between with the Tab key: Build, the default agent with full access, and Plan, which disables the ability to make changes. Start a new task in Plan, let it read the code and propose an approach, and only switch to Build when you agree with the plan. On a server, a read-only first pass is cheap insurance.

The blast radius, honestly

A coding agent is not passive, so say plainly what this setup does and does not contain. It does contain file damage: the opencode user owns its own home and nothing else, so edits and deletions stop at that boundary. It does contain credential exposure: the key lives in one file with mode 600, in one account. It does not contain what the account can legitimately do, so if the project directory holds production deploy credentials, the agent can use them; keep those out of the agent's account entirely.

Unlike a gateway agent such as OpenClaw, OpenCode is an interactive terminal program, not a daemon. It opens no listening port and has no long-running service, so there is no systemd unit to write and no port to firewall for the agent itself. The containment is the user account and the project directory, which is why the first section of this guide is the one that matters most.

The box around it still needs the standard care, because a coding VPS is still a public server: key-only SSH with root login disabled, as in SSH hardening on a VPS, a default-deny firewall, and routine updates. And review what the agent produces. Read its diffs before you push them, the same way you would read a pull request from a new contributor, because you are the one who deploys the result.

Finally, keep the tool itself current. OpenCode releases often, and updates carry fixes that matter for a program that runs commands on your server. Updating uses the same route you installed with: rerun the install script as the opencode user, or run sudo npm update -g opencode-ai if you installed through npm, then confirm the new version with opencode --version. A minute of maintenance now and then is cheaper than debugging behavior a months-old build already fixed.

FAQ

Can OpenCode use a local model instead of a paid API?

Yes. OpenCode treats any OpenAI-compatible server as a provider, so a model served by Ollama on the same VPS works: declare the provider in opencode.json with the local baseURL and the model name Ollama reports. The catch is hardware, because a model good enough for real coding work needs serious memory, so size the server for the model before you download it.

How do I keep OpenCode running after I close my laptop?

Run it inside tmux on the VPS. Start the agent in a named session with tmux new -s opencode, detach with Ctrl-b then d, and the session keeps running on the server after your SSH connection ends. Reattach any time with tmux attach -t opencode and the conversation and any running task are still there. A server reboot ends the session, so start a fresh one after a reboot.

Is it safe to let OpenCode run commands on my VPS?

It is manageable if you contain it. Give OpenCode a dedicated unprivileged user with no sudo, keep its projects in git so every edit is reversible, store the API key in a file with mode 600, and use its Plan agent for a read-only first pass before you let the Build agent change anything. The agent can then only damage what its own account owns, and the rest of the server stays out of reach.

What is the difference between OpenCode and Claude Code?

OpenCode is open source (MIT) and provider agnostic, connecting to more than 75 model providers, including local ones, through one interface. Claude Code is Anthropic's own terminal agent, built around Anthropic's models. If you want one tool across many providers, or a fully self-hosted stack with a local model, OpenCode is the fit; both run well on a VPS inside tmux with the same unprivileged-user setup.