How to Run OpenCode for VPS with tmux

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 from terminal user interface (TUI). E get MIT license, e connect to more than 75 model providers, and with about 165,000 GitHub stars as of mid-2026, na im be the open source coding agent wey get the most stars. To run OpenCode for VPS, you install am under dedicated unprivileged user, put your model API key for private file, and start am inside tmux so the session go survive when your connection drop. This guide dey do exactly that, for that order.

One naming note fit prevent confusion. The canonical repository na anomalyco/opencode, and Anomaly team dey maintain am (dem bin know am before as SST). The project bin dey at sst/opencode before. Another unrelated repository wey get name opencode-ai/opencode dey for GitHub too, so check say na the correct project's docs you dey read. The official site na opencode.ai.

Wetin make you run OpenCode for VPS

Coding agent session fit long. OpenCode fit spend plenty minutes dey work through refactor or test suite. If e dey run for your laptop, closing lid or Wi-Fi connection wey drop fit kill the session before task finish. For VPS inside tmux, agent go continue work after you disconnect, and you fit attach again later to read wetin e do. Na the same pattern as running Claude Code for VPS with tmux, and na the biggest quality-of-life benefit of moving agent comot from your laptop.

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

If you still dey choose tool, running coding AI agent for VPS compare the wider field, including Aider and Goose.

Give OpenCode im own user

Make we start with the honest point: coding agent dey edit files and run commands. Na im work, and na the risk too. OpenCode go run builds, tests, and any shell command wey the task seem to need, but the model judgement good, e no perfect. The account wey the agent dey use set the limit of wetin bad command fit reach. So no run am as root, and no run am as the same user wey dey administer the 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 the projects wey you want am to work on under /home/opencode, and make that user clone dem. Give the account no sudo rights. If the agent run destructive command, e fit only destroy wetin this one account own. Na the same reason as running services as unprivileged user. Also work inside git repository, because repository fit turn any bad edit into a git revert instead of total loss.

Install OpenCode

Project documentation dey show two ways to install am. Install script na the quickest one, and if you run am as the opencode user, everything go stay inside that user's home:

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

The usual curl | bash practice still apply here: for server wey matter to you, download the script first, read am, then run am. After installation finish, start new shell so PATH change wey installer make go take effect, then check whether binary dey answer:

opencode --version

If you prefer package manager and Node.js already dey for the machine, npm method go install the same tool system-wide. This one puts the opencode binary for PATH for every user:

sudo npm install -g opencode-ai

Either way, check na the same: opencode --version go print version number. If you see command not found after script installation, e mean say current shell never read the updated PATH. Log out, then log back in as the opencode user.

Put API key for 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 file wey only the opencode user fit read, with mode 600. Keep the key there instead of typing am inside commands, where e go enter your shell history:

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

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

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

OpenCode get interactive alternative too: the /connect command inside the TUI go guide you to add provider and save the credential to ~/.local/share/opencode/auth.json for the user's home directory. If you use this method, confirm say the file private with chmod 600 ~/.local/share/opencode/auth.json. Both methods keep the key out of your command lines. Choose one and use am consistently.

Start OpenCode inside tmux

tmux na wetin make VPS setup worth am, because tmux session dey continue to run when your SSH connection end. Start one, enter your project, then launch the agent:

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

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

tmux attach -t opencode

The session, the conversation, and any task wey dey run go remain exactly where you leave dem. This one survive disconnection, but e no survive server reboot, so after reboot you go start fresh tmux session the same way. Nothing stop you from opening second tmux window and running another agent beside the first one. But OpenCode sessions remain independent from each other, while Claude Code sessions for the same box fit send messages to each other, and this na another way to split one job into two.

Set am point to one model

OpenCode no dey tied to one provider. E dey use AI SDK and Models.dev catalog to support more than 75 providers, so the same tool fit work with Anthropic, OpenAI, Google, and plenty others, including local servers. The quick way na to use the /connect command inside TUI. E go list providers and handle the credential. If you want setup wey you fit commit and reproduce, put one opencode.json for project root and set the model as provider/model-id:

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

Local model fit work through the same file, because any OpenAI-compatible server fit be provider. If you 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 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 habit wey good make you start with from day one na this. OpenCode ship with two agents wey you fit switch between with Tab key: Build, the default agent wey get full access, and Plan, wey disable the ability to make changes. Start new task for Plan. Allow am read the code and suggest approach. Only switch to Build when you agree with the plan. For server, read-only first pass na cheap protection. Claude Code describe the same choice as permission modes instead of agents, and the way e switch to auto mode as default worth reading if you dey run both tools, because the mode wey session start with go decide how much agent wey nobody dey watch fit change.

The damage boundary, make we talk am plainly

Coding agent no dey passive, so make we clearly state wetin this setup contain and wetin e no contain. E contain file damage: opencode user own only its home directory and nothing else, so edits and deletions go stop for that boundary. E contain credential exposure: the key dey inside one file with mode 600, for one account. E no contain wetin the account fit legitimately do, so if production deploy credentials dey inside the project directory, agent fit use dem; keep those credentials completely outside the agent's account.

Unlike gateway agent like OpenClaw, OpenCode na interactive terminal program, no be daemon. E no open any listening port and e get no long-running service, so no systemd unit dey to write and no port dey to firewall for the agent itself. User account and project directory na the containment boundary, na why the first section of this guide matter pass.

The server around am still need standard care, because coding VPS still be public server: key-only SSH with root login disabled, as e dey for SSH hardening for VPS, default-deny firewall, and regular updates. Also review wetin agent produce. Read its diffs before you push dem, the same way you go read pull request from new contributor, because na you dey deploy the result.

Finally, keep the tool itself current. OpenCode dey release often, and updates carry fixes wey matter for program wey dey run commands for your server. To update am, use the same method wey you use install am: rerun the install script as opencode user, or run sudo npm update -g opencode-ai if you install am through npm, then confirm the new version with opencode --version. Small maintenance from time to time cheaper pass debugging behaviour wey month-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 model wey Ollama serve for the same VPS go work: declare the provider for opencode.json with the local baseURL and the model name wey Ollama report. The main issue na hardware, because model wey good reach for real coding work need serious memory. So size the server for the model before you download am.

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

Run am inside tmux for the VPS. Start the agent inside named session with tmux new -s opencode. Detach with Ctrl-b then d, and the session go continue to run for the server after your SSH connection end. Reattach any time with tmux attach -t opencode, and the conversation plus any task wey dey run still dey there. Server reboot go end the session, so start fresh one after reboot.

E safe make OpenCode run commands for my VPS?

You fit manage the risk if you contain am. Give OpenCode dedicated unprivileged user wey no get sudo. Keep its projects for git so every edit fit reverse. Store the API key inside file wey get mode 600. Use its Plan agent for read-only first pass before you allow the Build agent change anything. The agent go only fit damage wetin its own account own, while the rest of the server remain out of reach.

Wetin be the difference between OpenCode and Claude Code?

OpenCode na open source (MIT) and e no depend on one provider. E connect to more than 75 model providers, including local ones, through one interface. Claude Code na Anthropic own terminal agent, and Anthropic models dey form the base of am. If you want one tool across many providers, or fully self-hosted stack with local model, OpenCode fit you better. Both fit run well for VPS inside tmux with the same unprivileged-user setup.