Paano i-setup ang OpenCode sa VPS

Ano ang OpenCode, at ano ang iyong i-setup

Ang OpenCode ay isang open source AI coding agent na ginawa para sa terminal. Sinisimulan ito sa loob ng isang project directory. Binabasa nito ang iyong code, nagmumungkahi ng mga pagbabago, nag-e-edit ng mga file, at nagpapatakbo ng mga command gamit ang terminal user interface (TUI). Ito ay MIT licensed at kumokonekta sa mahigit 75 model providers. Mayroon itong humigit-kumulang 165,000 GitHub stars noong mid-2026, kaya ito ang may pinakamataas na star count na open source coding agent. Para mapatakbo ang OpenCode sa isang VPS, i-install ito sa ilalim ng isang dedicated unprivileged user, ilagay ang iyong model API key sa isang private file, at patakbuhin ito sa loob ng tmux para hindi mawala ang session kapag naputol ang koneksyon. Ito ang gagawin ng guide na ito, ayon sa tamang pagkakasunod-sunod.

Isang paalala tungkol sa pangalan para maiwasan ang kalituhan. Ang canonical repository ay anomalyco/opencode, na pinapanatili ng Anomaly team (dating kilala bilang SST), at ang project ay dati sa sst/opencode nakatira. Mayroon ding isang lumang repository na opencode-ai/opencode sa GitHub na walang kaugnayan sa proyektong ito, kaya siguraduhing ang tamang docs ng proyekto ang iyong binabasa. Ang official site ay opencode.ai.

Bakit dapat patakbuhin ang OpenCode sa isang VPS

Mahaba ang coding agent session. Maaaring gumugol ang OpenCode ng maraming minuto sa pag-refactor o pagpapatakbo ng test suite. Kung sa laptop ito patatakbuhin, mapuputol ang session sa gitna ng task kapag naisara ang lid o nawala ang Wi-Fi connection. Kapag nasa VPS ito gamit ang tmux, magpapatuloy ang trabaho ng agent kahit disconnected ka na, at maaari mo itong i-reattach mamaya para basahin ang resulta. Katulad ito ng pattern sa pagpapatakbo ng Claude Code sa isang VPS gamit ang tmux, at ito ang pinakamalaking benepisyo ng paglilipat ng agent mula sa iyong laptop.

Ang ikalawang dahilan ay ang placement. Ang VPS ay malapit sa code na iyong dine-deploy: ang repository, build tools, test database, at madalas ay ang staging environment ay naroon na o malapit sa server. Mas mahusay ang trabaho ng agent na nag-e-edit ng code at nagpapatakbo ng tests kung nasa machine ito kung saan talaga tumatakbo ang mga tests na iyon. Dahil kontrolado mo ang server, maaari kang magbigay ng isang contained environment para sa agent, na tatalakayin sa susunod na seksyon.

Kung naghahanap ka pa ng tool, ihahambing ng pagpapatakbo ng coding AI agent sa isang VPS ang iba't ibang opsyon, kabilang ang Aider at Goose.

Bigyan ang OpenCode ng sariling user

Narito ang katotohanan: ang isang coding agent ay nag-e-edit ng mga file at nagpapatakbo ng mga command. Iyan ang trabaho nito, at iyan din ang panganib. Patatakbuhin ng OpenCode ang mga build, test, at anumang shell command na kailangan sa task. Maganda ang judgement ng model pero hindi ito perpekto. Ang account na ginagamit ng agent ang magtatakda ng limitasyon kung ano ang maaaring maabot ng isang maling command. Huwag itong patakbuhin bilang root, at huwag itong patakbuhin gamit ang user na nag-a-administer sa server.

Hindi tulad ng isang background agent, interactive ang OpenCode, kaya ang user nito ay kailangan ng real shell at home directory:

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

Ilagay ang mga project na gusto mong i-work nito sa ilalim ng /home/opencode, na i-clone gamit ang user na iyon. Huwag bigyan ang account ng sudo rights. Kung magpapatakbo ang agent ng isang destructive command, ang maaari lang nitong masira ay ang mga pagmamay-ari ng account na ito. Ito ang parehong dahilan kung bakit running services as an unprivileged user. Magtrabaho rin sa loob ng isang git repository, dahil ginagawa ng repository ang anumang maling edit bilang isang git revert sa halip na tuluyang pagkawala ng data.

Install OpenCode

May dalawang paraan ng pag-install sa dokumentasyon ng project. Ang pinakamabilis ay ang paggamit ng install script. Kapag pinatakbo ito bilang opencode user, mananatili ang lahat sa loob ng home directory ng user na iyon:

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

Dapat sundin ang karaniwang curl | bash habit: i-download muna ang script sa server na iyong pinapahalagahan, basahin ito, at saka patakbuhin. Pagkatapos ng install, magbukas ng bagong shell para maging epektibo ang pagbabago sa PATH na ginawa ng installer, pagkatapos ay i-verify ang binary:

opencode --version

Kung mas gusto mo ang package manager at naka-install na ang Node.js sa system, ang npm route ay mag-i-install ng parehong tool sa buong system. Dahil dito, ang opencode binary ay magiging nasa PATH para sa lahat ng user:

sudo npm install -g opencode-ai

Sa alinmang paraan, pareho lang ang verification: magpi-print ang opencode --version ng version number. Ang command not found pagkatapos ng script install ay nangangahulugang hindi pa nababasa ng kasalukuyang shell ang updated na PATH, kaya mag-log out at mag-log in muli bilang opencode user.

Ilagay ang API key sa isang private file

Kailangan ng OpenCode ng key para sa anumang model provider na gamit mo. Maaaring magastos ang paggamit nito, kaya ituring itong parang password. Gumawa ng file na ang opencode user lang ang makakabasa gamit ang mode 600. I-save ang key doon sa halip na i-type ito nang direkta sa mga command para hindi ito ma-record sa shell history:

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

Ilagay ang variable ng iyong provider sa loob ng file, halimbawa ang ANTHROPIC_API_KEY=... o ang katumbas nito para sa iyong provider, dahil binabasa ng OpenCode ang mga standard provider environment variables. I-load ang file sa iyong shell bago i-start ang agent:

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

May interactive alternative din ang OpenCode: ang /connect command sa loob ng TUI ang gagabay sa iyo para magdagdag ng provider at i-save ang credential sa ~/.local/share/opencode/auth.json sa home directory ng user. Kung ito ang gagamitin mo, i-verify na private ang file gamit ang chmod 600 ~/.local/share/opencode/auth.json. Parehong paraan ang naglalayo sa key mula sa iyong mga command line; pumili ng isa at panatilihin itong consistent.

Simulan ang OpenCode sa loob ng tmux

Ang tmux ang dahilan kung bakit sulit ang VPS setup, dahil nananatiling tumatakbo ang tmux session kahit maputol ang SSH connection. Mag-start ng session, pumunta sa iyong project directory, at i-launch ang agent:

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

Dapat magbukas ang TUI na may prompt sa ibaba at ang pangalan ng iyong project sa interface. Magbigay ng task gamit ang simpleng lengguwahe, at magsisimula itong magbasa ng mga file at magmungkahi ng mga pagbabago. Para umalis, i-detach gamit ang Ctrl-b tapos d, at patuloy na gagana ang agent kahit nakasara ang iyong laptop. Mag-reattach muli gamit ang:

tmux attach -t opencode

Ang session, ang conversation, at anumang running task ay mananatili kung saan mo ito iniwan. Hindi ito mawawala kahit magkaroon ng disconnection, pero mawawala ito kapag nag-reboot ang server. Pagkatapos ng reboot, mag-start muli ng bagong tmux session sa parehong paraan.

Ituro ito sa isang model

Provider agnostic ang OpenCode. Gumagamit ito ng AI SDK at Models.dev catalog para suportahan ang higit sa 75 providers. Dahil dito, gumagana ang tool sa Anthropic, OpenAI, Google, at marami pang iba, kabilang ang mga local server. Ang pinakamabilis na paraan ay ang paggamit ng /connect command sa loob ng TUI; inililista nito ang mga provider at inaayos ang credentials. Para sa setup na pwedeng i-commit at i-reproduce, maglagay ng opencode.json sa project root at i-set ang model bilang provider/model-id:

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

Gumagana ang local model gamit ang parehong file, dahil ang anumang OpenAI-compatible server ay pwedeng ideklara bilang provider. Kung mag-serve ka ng model gamit ang Ollama sa parehong VPS, ituturo ng config ang local API nito. Ang model name ay kung ano ang ipinapakita ng ollama list sa iyong 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" } }
    }
  }
}

May isang built-in habit na dapat gamitin mula sa simula. May dalawang agent ang OpenCode na pwedeng pagpalitin gamit ang Tab key: ang Build, ang default agent na may full access, at ang Plan, na naka-disable ang kakayahang gumawa ng mga pagbabago. Simulan ang bagong task sa Plan, hayaan itong basahin ang code at magmungkahi ng approach, at lumipat lamang sa Build kapag sang-ayon ka na sa plano. Sa isang server, ang read-only na unang pass ay isang murang insurance.

Ang blast radius, sa totoo lang

Hindi passive ang isang coding agent, kaya dapat malinaw kung ano ang sakop at hindi sakop ng setup na ito. Kasama sa risk ang file damage: ang opencode user ay may ownership lamang sa sarili nitong home directory at wala nang iba, kaya ang mga edit at deletion ay hihinto sa boundary na iyon. Kasama rin ang credential exposure: ang key ay nasa isang file na may mode 600, sa loob ng isang account. Hindi kasama sa limitasyon ang mga legal na gawain ng account, kaya kung ang project directory ay may production deploy credentials, magagamit ito ng agent; panatilihing hiwalay ang mga ito sa account ng agent.

Hindi gaya ng isang gateway agent tulad ng OpenClaw, ang OpenCode ay isang interactive terminal program, hindi isang daemon. Hindi ito nagbubukas ng listening port at walang long-running service, kaya walang kailangang isulat na systemd unit at walang port na kailangang i-firewall para sa agent mismo. Ang containment ay ang user account at ang project directory, kaya ang unang seksyon ng guide na ito ang pinakamahalaga.

Kailangan pa rin ng standard care ang server, dahil ang isang coding VPS ay isa pa ring public server: key-only SSH na naka-disable ang root login, gaya ng nasa SSH hardening sa isang VPS, isang default-deny firewall, at regular na updates. At suriin ang output ng agent. Basahin ang mga diff nito bago i-push, gaya ng pagbabasa ng pull request mula sa isang bagong contributor, dahil ikaw ang magdedeploy ng resulta.

Panghuli, panatilihing updated ang tool mismo. Madalas mag-release ang OpenCode, at ang mga update ay may mga fix na mahalaga para sa program na nagpapatakbo ng mga command sa iyong server. Ang pag-update ay gumagamit ng parehong paraan kung paano ito ininstall: i-rerun ang install script bilang opencode user, o i-run ang sudo npm update -g opencode-ai kung ininstall ito via npm, pagkatapos ay i-confirm ang bagong version gamit ang opencode --version. Ang ilang minutong maintenance ngayon ay mas mura kaysa sa pag-debug ng behavior na naayos na sana ng isang lumang build.

FAQ

Maaari bang gumamit ang OpenCode ng local model sa halip na paid API?

Oo. Itinuturing ng OpenCode ang anumang OpenAI-compatible server bilang provider. Gumagana ang model na served ng Ollama sa parehong VPS: i-declare ang provider sa opencode.json gamit ang local baseURL at ang model name na ibinibigay ng Ollama. Ang limitasyon ay ang hardware, dahil nangangailangan ng malaking memory ang model na sapat para sa coding work. Siguraduhing tama ang laki ng server para sa model bago ito i-download.

Paano mapapanatiling tumatakbo ang OpenCode kahit nakasara ang laptop?

Patakbuhin ito sa loob ng tmux sa VPS. Simulan ang agent sa isang named session gamit ang tmux new -s opencode, i-detach gamit ang Ctrl-b tapos d, at mananatiling tumatakbo ang session sa server kahit matapos ang SSH connection. Maaaring mag-reattach anumang oras gamit ang tmux attach -t opencode at nandoon pa rin ang conversation at anumang running task. Magtatapos ang session kapag nag-reboot ang server, kaya magsimula ng bagong session pagkatapos ng reboot.

Ligtas ba na hayaan ang OpenCode na magpatakbo ng commands sa aking VPS?

Maaari itong i-manage kung may limitasyon ang access nito. Bigyan ang OpenCode ng dedicated unprivileged user na walang sudo access, panatilihin ang mga project sa git para ma-reverse ang bawat edit, i-store ang API key sa isang file na may mode 600, at gamitin ang Plan agent para sa read-only na unang pass bago payagan ang Build agent na magbago ng kahit ano. Sa ganitong paraan, ang maaari lamang maapektuhan ng agent ay ang mga file na pagmamay-ari ng account nito, at mananatiling ligtas ang ibang bahagi ng server.

Ano ang pagkakaiba ng OpenCode at Claude Code?

Ang OpenCode ay open source (MIT) at provider agnostic. Nakakakonekta ito sa higit sa 75 model providers, kabilang ang mga local provider, sa pamamagitan ng isang interface. Ang Claude Code ay terminal agent ng Anthropic na nakabase sa mga model ng Anthropic. Kung kailangan mo ng isang tool para sa maraming providers, o isang fully self-hosted stack na may local model, ang OpenCode ang angkop; parehong maayos ang takbo ng dalawa sa VPS sa loob ng tmux gamit ang parehong unprivileged-user setup.