how to run OpenCode for VPS

Wetin OpenCode be, and wetin you dey set up

OpenCode na open source AI coding agent wey dem build for terminal. You start am inside project directory, and e go read your code, suggest changes, edit files, and run commands, all inside terminal user interface (TUI). E get MIT license, e connect to more than 75 model providers, and with roughly 165,000 GitHub stars as of mid-2026, na di most-starred open source coding agent wey dey exist. To run OpenCode for VPS, you go install am under one dedicated unprivileged user, put your model API key inside one private file, and start am inside tmux so di session no go die when your connection drop. Dis guide go show you how to do all dem, one by one.

One thing wey you must know so confusion no go plenty. Di official repository na anomalyco/opencode, wey di Anomaly team (wey dem call SST before) dey maintain, and di project dey live for sst/opencode. One old repository wey no get connection to dis one, wey dem call opencode-ai/opencode, dey exist for GitHub too, so make sure say you dey read di correct project docs. Di official site na opencode.ai.

Why run OpenCode on a VPS

Coding agent session dey long. OpenCode fit spend many minutes dey work for refactor or test suite. If you run am for your laptop, if you close lid or Wi-Fi disconnect, the session go die mid-task. If you run am for VPS inside tmux, the agent go continue to work even after you disconnect, and you fit reattach later to see wetin e do. This one na the same pattern as running Claude Code on a VPS with tmux, and na the biggest way to make work easy when you move agent from your laptop.

The second reason na placement. VPS dey close to the code wey you dey deploy: the repository, the build tools, the test database, and often the staging environment dey there or near am. Agent wey dey edit code and run tests go work best for the machine wey dem dey run those tests for. And because the box na server wey you control, you fit give the agent one contained environment, wetin the next section go explain.

If you still dey choose tool, running a coding AI agent on a VPS dey compare all the options, including Aider and Goose.

Give OpenCode its own user

Dis na di real truth: coding agent dey edit files and run commands. Na dat na im job, and na dat also be di risk. OpenCode go run builds, tests, and any shell commands wey di task need. Di model judgement dey good, but e no perfect. Di account wey di agent dey use na di limit for wetin bad command fit do. So, no run am as root, and no run am as di same user wey dey administer di server.

Unlike background agent, OpenCode dey interactive, so im user need real shell and home directory:

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

Keep di projects wey you want am to work on under /home/opencode, and make dat user clone dem. No give di account sudo rights. If di agent run bad command wey go destroy things, e fit only destroy wetin dis one account own. Na di same reason as running services as an unprivileged user. Work inside git repository too, because repository go turn any bad edit to git revert instead of total loss.

Install OpenCode

Dis project get two ways to install am. Di install script na di fastest way, and if you run am as opencode user, everything go stay inside dat user home directory:

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

Di usual curl | bash rule apply for here as e dey apply for everywhere: if na server wey you dey care about, download di script first, read am well, den run am. After di install finish, open new shell so dat di PATH change wey di installer make go work, den check if di binary dey answer:

opencode --version

If you prefer to use package manager and Node.js don dey di box already, di npm route go install di same tool for di whole system, wey go put di opencode binary for di PATH for every user:

sudo npm install -g opencode-ai

No matter which way you choose, di check na di same: opencode --version go print version number. If you see command not found after you run di script install, e mean say di current shell never read di new PATH yet, so log out and log back in as di opencode user.

Put the API key inside private file

OpenCode need key for any model provider wey you dey use. That key fit spend your money, so treat am like password. Create one file wey only opencode user fit read, use mode 600, and keep the key inside there. No type am directly inside commands because e go show for your shell history:

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

Put your provider variable inside the file, for example ANTHROPIC_API_KEY=... or the one wey your provider dey use, because OpenCode dey pick standard provider environment variables. Load the file into your shell before you start the agent:

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

OpenCode get another way to do am: the /connect command inside the TUI go guide you how to add provider and e go save the credential for ~/.local/share/opencode/auth.json inside user home directory. If you use that way, check make sure say the file dey private with chmod 600 ~/.local/share/opencode/auth.json. Both ways dey keep the key out of your command lines; pick one and use am consistently.

Start OpenCode inside tmux

tmux na him dey make VPS setup worth am, because tmux session go still dey run even when your SSH connection end. Start one, enter your project folder, and launch the agent:

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

You go see TUI open with prompt for bottom and your project name for interface. Give am task for plain language, and e go start to read files and propose changes. When you wan leave, detach with Ctrl-b then d, and the agent go still dey work even if you close your laptop. Reattach later with:

tmux attach -t opencode

The session, the conversation, and any task wey dey run go still dey exactly where you leave dem. This one go survive when connection cut, but e no go survive if server reboot. So after reboot, you go start new tmux session the same way.

Point am at a model

OpenCode no dey depend on one single provider. E dey use AI SDK and Models.dev catalog so e fit work with more than 75 providers. This mean say the same tool dey work for Anthropic, OpenAI, Google, and many others, including local servers. The fast way na to use /connect command inside TUI, wey go list providers and handle your credentials. If you want setup wey you fit commit and use again, put opencode.json for your project root and set the model as provider/model-id:

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

Local model dey work through the same file, because any OpenAI-compatible server fit be provider. If you dey serve model with Ollama for the same VPS, the config go point to its local API, and the model name na wetin ollama list show for your machine:

{
  "$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 good habit wey you must start from day one na to use the two agents wey dey inside OpenCode. You fit switch between dem with Tab key: Build, wey na default agent with full access, and Plan, wey dey block the ability to make changes. Start new task for Plan, make e read the code and propose how to do am, and only switch to Build when you agree with the plan. For server, using read-only first pass na cheap insurance.

The blast radius, honestly

Coding agent no be passive thing, so make we talk wetin this setup fit do and wetin e no fit do. E fit damage files: the opencode user own him own home directory and nothing else, so any edit or delete go stop for that boundary. E fit expose credentials: the key dey inside one file with mode 600, inside one account. E no fit control wetin the account fit do legitimately, so if the project directory get production deploy credentials, the agent fit use dem; keep dem far from the agent account entirely.

Unlike gateway agent like OpenClaw, OpenCode na interactive terminal program, e no be daemon. E no open any listening port and e no get long-running service, so you no need write any systemd unit and you no need firewall any port for the agent itself. The containment na the user account and the project directory, na why the first section of this guide na the most important one.

The box around am still need standard care, because coding VPS still be public server: use key-only SSH with root login disabled, like we talk for SSH hardening on a VPS, use default-deny firewall, and do routine updates. And check wetin the agent produce. Read him diffs before you push dem, just like how you dey read pull request from new contributor, because na you go deploy the result.

Finally, keep the tool itself current. OpenCode dey release updates often, and updates carry fixes wey important for program wey dey run commands for your server. To update, use the same route wey you use install am: rerun the install script as the opencode user, or run sudo npm update -g opencode-ai if you install through npm, then confirm the new version with opencode --version. One minute of maintenance now and then cheap pass debugging behavior wey old build don already fix.

FAQ

OpenCode fit use local model instead of paid API?

Yes. OpenCode dey treat any OpenAI-compatible server as provider. So, if you dey use Ollama for the same VPS, e go work: just declare the provider for opencode.json with the local baseURL and the model name wey Ollama dey report. The only wahala na hardware. Model wey sabi coding well well need plenty memory, so make sure say your server get enough power before you download the model.

How I go take make OpenCode continue to run after I close my laptop?

Run am inside tmux for your VPS. Start the agent inside one named session with tmux new -s opencode, then press Ctrl-b and d to detach. The session go still dey run for server even after your SSH connection don end. You fit reattach any time with tmux attach -t opencode and the conversation and any task wey dey run go still dey there. If server reboot, the session go end, so you go need start new one after reboot.

Safe be to let OpenCode run commands for my VPS?

E dey safe if you control am well. Give OpenCode one dedicated unprivileged user wey no get sudo access. Keep all your projects inside git so you fit undo any edit. Store your API key for one file wey get mode 600. Also, use the Plan agent for first pass to read only, before you let the Build agent change anything. This way, the agent fit only touch wetin its own account own, and the rest of the server go safe.

Wetin be difference between OpenCode and Claude Code?

OpenCode na open source (MIT) and e no dey stick to one provider. E fit connect to more than 75 model providers, including local ones, through one interface. Claude Code na Anthropic terminal agent wey dem build for their own models. If you want one tool wey fit work with many providers, or you want full self-hosted stack with local model, OpenCode na the right choice. Both of dem dey run well for VPS inside tmux with the same unprivileged-user setup.