How to Run OpenCode for VPS with tmux

Wetin be OpenCode, and wetin you dey set up

OpenCode na open source AI coding agent wey dey work for terminal. You go 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 219,000 GitHub stars as of October 2026, na the open source coding agent wey get the most stars. To run OpenCode for VPS, install am under dedicated unprivileged user, put your model API key for private file, and start am inside tmux so the session go survive if your connection drop. This guide dey do exactly that, for that order.

One naming matter fit prevent confusion. The canonical repository na anomalyco/opencode, wey the Anomaly team maintain (dem bin know am before as SST), and the project bin dey for sst/opencode before. Another unrelated repository wey get name opencode-ai/opencode, wey dem don archive now, still dey for GitHub, so check well say na the correct project 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 matter: coding agent dey edit files and dey run commands. Na im work, and na im risk too. OpenCode go run builds, tests, and any shell command wey task seem to need, and model judgement good but e no perfect. The account wey agent dey use na 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. No give the account any sudo rights. If agent run destructive command, e fit only destroy wetin this account own. Na the same reason behind running services as unprivileged user. Work inside git repository too, and commit before you give agent task, because if bad edit affect committed work, na git revert or git restore go restore am instead of losing the work. Changes wey you never commit no get protection.

Install OpenCode

The project docs different installation methods, and two of dem fit server. The install script na the quickest one, and if you run am as opencode user, everything go remain inside that user's home:

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

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

opencode --version

If you prefer package manager and Node.js already dey for the machine, the npm method go install the same tool inside npm global prefix:

sudo npm install -g opencode-ai

With system-wide Node.js, that prefix normally dey be /usr/local or /usr, and the bin directory dey for every user's PATH. Version manager or custom prefix fit put the binary for another place, so run npm prefix -g first if you need make opencode dey find am as opencode user.

Either way, the 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, so log out and log back in as opencode user.

Both commands install OpenCode 1.x line, wey still dey release versions (1.19.3 on 16 October 2026), and this guide dey describe that line. OpenCode 2 don come out now as separate installation, from https://opencode.ai/v2/install or npm package @opencode/cli, and e work differently: shared background server for each user account dey own sessions, permissions, and tool execution, while terminal dey connect to am. The migration guide say make you remove package-managed 1.x installation before you install 2, because both use opencode command.

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.

Point am go one model

OpenCode no dey depend on 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 dozens of others, including local servers. The quick way na the /connect command inside the TUI, wey dey list providers and handle the credential. If you want setup wey you fit commit and reproduce, put an opencode.json for project root and set the model as provider/model-id:

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

Choose model wey your provider still dey serve: Anthropic retire claude-sonnet-4-20250514 on 15 June 2026, so configs wey still name am go fail.

Local model fit work through the same file, because any OpenAI-compatible server fit be declared as provider. If you serve model with Ollama for the same VPS, config go point to its local API, and model name go be whatever 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 built-in habit dey worth adopting from day one. OpenCode ships two agents wey you fit switch between with Tab key: Build, the default agent with full access, and Plan, a restricted agent for analysis wey dey refuse file edits outside its own plan directory without asking. Plan no be strictly read-only, though, because e fit still run shell commands, and shell command fit change files. Start new task for Plan, allow am read the code and propose approach, then switch to Build only when you agree with the plan. If you want that first pass to truly remain read-only, deny edits and shell commands for Plan in opencode.json, because OpenCode treats deny as blocking the action, while ask only prompts you for approval:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

For server, first pass wey no fit change anything na cheap insurance. Claude Code frames the same decision as permission modes instead of agents, and its shift to auto mode as the default dey worth reading if you run both tools, because the mode wey session start with decides how much an unwatched agent fit change.

The blast radius, frankly

Coding agent no be passive, so talk clearly about wetin this setup contain and wetin e no contain. E dey contain file damage: the opencode user own im home directory and nothing else, so edits and deletions go stop for that boundary. E dey 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, the agent fit use dem; keep those credentials completely outside the agent's account.

Unlike gateway agent like OpenClaw, OpenCode 1.x na interactive terminal program, no be daemon. By default, e no open any listening port (na only the --port, --hostname, or --mdns flags go make the TUI listen) and e no get long-running service, so no systemd unit to write and no port to firewall for the agent itself. OpenCode 2 change this with im shared background server, so check this point again before you migrate. The containment na the user account and the project directory, na why the first section of this guide matter pass.

The box around am still need standard care, because coding VPS still be public server: SSH wey key-only authentication dey use with root login disabled, as e dey for SSH hardening for VPS, default-deny firewall, and regular updates. And review wetin the agent produce. Read im 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: run the install script again as the opencode user, or run sudo npm update -g opencode-ai if you install am through npm, then confirm the new version with opencode --version. Both keep you for the 1.x line; moving to OpenCode 2 na separate migration. Small maintenance from time to time cheaper than debugging behaviour wey build wey old for months 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 dey serve for the same VPS fit 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 plenty memory. So size the server for the model before you download am.

How I go 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. You fit reattach anytime 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 new one after reboot.

E safe to allow OpenCode run commands for my VPS?

You fit manage am if you contain am. Give OpenCode dedicated unprivileged user wey no get sudo. Keep its projects for git and commit before each task, so you fit roll back bad edit. Store the API key inside file with mode 600. Use its Plan agent for first pass before you allow Build agent change anything. Set edits and shell commands to deny for Plan if you want that pass to be strictly read-only. 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, built around Anthropic models. If you want one tool wey fit work across many providers, or fully self-hosted stack with local model, OpenCode na the better fit. Both fit run well for VPS inside tmux with the same unprivileged-user setup.