Jinsi ya kuendesha OpenCode kwenye VPS kwa usalama

OpenCode ni nini, na unaandaa nini

OpenCode ni wakala wa AI wa kuandika msimbo (coding agent) wa chanzo huria ulioundwa kwa ajili ya terminal. Unaiwasha ndani ya saraka ya mradi, nayo inasoma msimbo wako, inapendekeza mabadiliko, inahariri faili, na kuendesha amri, yote hayo yakifanyika kupitia kiolesura cha mtumiaji cha terminal (TUI). Ina leseni ya MIT, inaunganishwa na watoa huduma wa modeli zaidi ya 75, na ikiwa na takriban nyota 165,000 kwenye GitHub kufikia katikati ya 2026, ndiyo wakala wa chanzo huria wa kuandika msimbo mwenye nyota nyingi zaidi uliopo. Ili kuendesha OpenCode kwenye VPS, unaisakinisha chini ya mtumiaji maalum asiye na upendeleo (unprivileged user), unaweka API key ya modeli yako kwenye faili la siri, na kuianzisha ndani ya tmux ili kikao kiendelee hata muunganisho wako ukikatika. Mwongozo huu unafanya hivyo hasa, kwa mpangilio huo.

Ujumbe mmoja kuhusu majina utasaidia kuepuka mkanganyiko. Hifadhi (repository) rasmi ni anomalyco/opencode, inayodumishwa na timu ya Anomaly (iliyojulikana awali kama SST), na mradi huu ulikuwa ukipatikana kwenye sst/opencode. Hifadhi nyingine ya zamani isiyohusiana inayoitwa opencode-ai/opencode pia ipo kwenye GitHub, kwa hivyo hakikisha unasoma nyaraka za mradi sahihi. Tovuti rasmi ni opencode.ai.

Kwa nini uendeshe OpenCode kwenye VPS

Kikao cha wakala wa uandishi wa msimbo (coding agent) huchukua muda mrefu. OpenCode inaweza kutumia dakika nyingi kufanya refactor au kuendesha test suite, na ikifanya kazi kwenye laptop yako, kufunga mfuniko au kukatika kwa Wi-Fi kutakatisha kikao hicho katikati ya kazi. Kwenye VPS ndani ya tmux, wakala huendelea kufanya kazi hata baada ya wewe kukata muunganisho, na unaweza kurejea baadaye kuona kile ilichokifanya. Hii ni mbinu sawa na kuendesha Claude Code kwenye VPS kwa kutumia tmux, na ndiyo faida kubwa zaidi ya kuboresha maisha ya kazi kwa kuhamisha wakala kutoka kwenye laptop yako.

Sababu ya pili ni mahali ilipo. VPS iko karibu na msimbo unaoudeploy: hazina ya msimbo (repository), zana za ujenzi (build tools), database ya majaribio, na mara nyingi mazingira ya staging tayari yapo hapo au karibu nayo. Wakala anayebadilisha msimbo na kuendesha majaribio hufanya kazi vizuri zaidi kwenye mashine ambapo majaribio hayo huendeshwa kihalisi. Na kwa sababu mashine hiyo ni seva unayoimiliki, unaweza kumpa wakala mazingira yaliyotengwa (contained environment) kwa makusudi, jambo ambalo sehemu inayofuata inalielezea.

Ikiwa bado unachagua zana, kuendesha wakala wa AI wa uandishi wa msimbo kwenye VPS inalinganisha uwanja mpana zaidi, ikijumuisha Aider na Goose.

Mpatie OpenCode mtumiaji wake mwenyewe

Hapa ndipo mahali sahihi pa kuanzia: wakala wa uandishi wa msimbo (coding agent) huhariri faili na kuendesha amri. Hiyo ndiyo kazi yake, na pia ndiyo hatari yake. OpenCode itaendesha builds, majaribio, na amri zozote za shell ambazo kazi husika inahitaji, na uamuzi wa modeli ni mzuri lakini si mkamilifu. Akaunti inayotumiwa na wakala huyu ndiyo kikomo cha kile ambacho amri mbaya inaweza kufikia, kwa hivyo usiendeshe kama root, na usiendeshe kama mtumiaji yuleyule anayesimamia seva.

Tofauti na wakala wa nyuma (background agent), OpenCode ni shirikishi, kwa hivyo mtumiaji wake anahitaji shell halisi na saraka ya nyumbani (home directory):

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

Weka miradi unayotaka ifanyiwe kazi chini ya /home/opencode, iliyokopiwa (cloned) na mtumiaji huyo. Usipe akaunti hiyo haki za sudo. Ikiwa wakala ataendesha amri ya uharibifu, anaweza kuharibu tu kile ambacho akaunti hii inamiliki, ambayo ni hoja ileile kama ya kuendesha huduma kama mtumiaji asiye na upendeleo. Fanya kazi ndani ya git repository pia, kwa sababu repository hugeuza uhariri wowote mbaya kuwa git revert badala ya upotevu wa data.

Kusakinisha OpenCode

Mradi huu unaelezea njia mbili za usakinishaji. Hati ya usakinishaji ndiyo njia ya haraka zaidi, na kuiendesha kama mtumiaji opencode huweka kila kitu ndani ya saraka ya nyumbani ya mtumiaji huyo:

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

Mazoea ya kawaida ya curl | bash yanatumika hapa kama ilivyo kila mahali: kwenye seva unayojali, pakua hati kwanza, isome, kisha uiendeshe. Baada ya usakinishaji, anzisha shell mpya ili mabadiliko ya PATH yanayofanywa na kisakinishi yaanze kufanya kazi, kisha thibitisha majibu ya binary:

opencode --version

Ikiwa unapendelea kutumia kiongozi wa vifurushi (package manager) na Node.js tayari ipo kwenye seva, njia ya npm husakinisha zana hiyo hiyo kwenye mfumo mzima, jambo ambalo huweka binary ya opencode kwenye PATH kwa kila mtumiaji:

sudo npm install -g opencode-ai

Vyovyote vile, uthibitishaji ni uleule: opencode --version huchapisha nambari ya toleo. command not found baada ya usakinishaji wa hati inamaanisha kuwa shell ya sasa haijasoma PATH iliyosasishwa bado, kwa hivyo ondoka (log out) na uingie tena kama mtumiaji opencode.

Hifadhi API key kwenye faili la siri

OpenCode inahitaji key kwa ajili ya mtoa huduma yeyote wa model unayotumia, na key hiyo inaweza kutumia pesa zako, kwa hivyo itendee kama nenosiri. Unda faili ambalo mtumiaji wa opencode pekee ndiye anayeweza kulisoma, kwa kutumia mode 600, na uweke key hiyo hapo badala ya kuiandika kwenye amri ambapo ingehifadhiwa kwenye shell history yako:

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

Weka variable ya mtoa huduma wako ndani yake, kwa mfano ANTHROPIC_API_KEY=... au inayolingana na mtoa huduma wako, kwa sababu OpenCode hutumia standard environment variables za mtoa huduma. Pakia faili hilo kwenye shell yako kabla ya kuanzisha agent:

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

OpenCode pia ina njia mbadala ya mwingiliano: amri ya /connect ndani ya TUI inakuongoza katika kuongeza mtoa huduma na kuhifadhi credential kwenye ~/.local/share/opencode/auth.json katika home directory ya mtumiaji. Ikiwa utatumia njia hiyo, thibitisha kuwa faili hilo ni la siri kwa kutumia chmod 600 ~/.local/share/opencode/auth.json. Njia zote mbili huweka key mbali na command lines zako; chagua moja na uendelee kuitumia.

Anzisha OpenCode ndani ya tmux

tmux ndiyo inayofanya usanidi wa VPS kuwa na thamani, kwa sababu session ya tmux huendelea kufanya kazi hata muunganisho wako wa SSH utakapokatika. Anzisha session, ingia kwenye folda ya mradi wako, na uwashe agent:

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

Unapaswa kuona TUI ikifunguka ikiwa na prompt chini na jina la mradi wako kwenye interface. Ipe kazi kwa lugha ya kawaida, nayo itaanza kusoma faili na kupendekeza mabadiliko. Unapotaka kuondoka, detach kwa kubonyeza Ctrl-b kisha d, na agent ataendelea kufanya kazi huku kompyuta yako ikiwa imefungwa. Unganisha tena baadaye kwa kutumia:

tmux attach -t opencode

Session, mazungumzo, na kazi yoyote inayoendelea vitakuwa pale ulipoviacha. Hii hustahimili kukatika kwa muunganisho, lakini si kuanzishwa upya kwa seva (reboot), kwa hivyo baada ya reboot unaanzisha session mpya ya tmux kwa njia ile ile. Hakuna kinachokuzuia kufungua dirisha la pili la tmux na kuendesha agent mwingine kando ya wa kwanza, ingawa session za OpenCode hubaki zikiwa huru dhidi ya nyingine, ilhali session za Claude Code kwenye mashine moja zinaweza kutumiana ujumbe, ambayo ni njia tofauti ya kugawanya kazi katika sehemu mbili.

Elekeza kwenye model

OpenCode haifungwi na mtoa huduma mmoja. Inatumia AI SDK na katalogi ya Models.dev kusaidia zaidi ya watoa huduma 75, kwa hivyo zana hiyo hiyo inafanya kazi na Anthropic, OpenAI, Google, na wengine wengi, ikiwemo seva za ndani. Njia ya haraka ni amri ya /connect ndani ya TUI, ambayo huorodhesha watoa huduma na kushughulikia vitambulisho. Kwa usanidi unaoweza kuuhifadhi kwenye version control na kuurudia, weka opencode.json kwenye mzizi wa mradi na uweke model kama provider/model-id:

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

Model ya ndani hufanya kazi kupitia faili hilohilo, kwa sababu seva yoyote inayooana na OpenAI inaweza kutangazwa kama mtoa huduma. Ikiwa unaendesha model na Ollama kwenye VPS hiyo hiyo, usanidi huelekeza kwenye API yake ya ndani, na jina la model ni lile ambalo ollama list inaonyesha kwenye mashine yako:

{
  "$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" } }
    }
  }
}

Kuna mazoea moja yaliyojengwa ndani ambayo yanafaa kuanza nayo tangu siku ya kwanza. OpenCode inakuja na mawakala wawili unaoweza kubadilishana nao kwa kutumia kitufe cha Tab: Build, wakala chaguo-msingi mwenye uwezo kamili, na Plan, ambayo huzima uwezo wa kufanya mabadiliko. Anza kazi mpya ukiwa kwenye Plan, iruhusu isome msimbo na kupendekeza mbinu, na ubadilie kwenda Build pale tu unapokubaliana na mpango huo. Kwenye seva, hatua ya kwanza ya kusoma tu ni bima ya bei nafuu. Claude Code huainisha uamuzi huo huo kama njia za ruhusa badala ya mawakala, na mabadiliko yake kuelekea hali ya otomatiki kama chaguo-msingi inafaa kusomwa ikiwa unaendesha zana zote mbili, kwa sababu hali ambayo kipindi huanza nayo huamua kiasi ambacho wakala asiyesimamiwa anaweza kubadilisha.

Upeo wa athari, kwa uwazi

Wakala wa uandishi wa msimbo si tulivu, kwa hivyo eleza wazi kile usanidi huu unachofanya na kisichofanya. Unahusisha uharibifu wa faili: mtumiaji opencode anamiliki saraka yake ya nyumbani pekee na si kingine, kwa hivyo uhariri na ufutaji huishia kwenye mpaka huo. Unahusisha ufichuzi wa vitambulisho: ufunguo unakaa kwenye faili moja yenye mode 600, katika akaunti moja. Hahusishi kile akaunti inaweza kufanya kihalali, kwa hivyo ikiwa saraka ya mradi ina vitambulisho vya kupeleka programu kwenye uzalishaji (production), wakala anaweza kuvitumia; viweke mbali kabisa na akaunti ya wakala.

Tofauti na wakala wa lango kama OpenClaw, OpenCode ni programu ya terminal shirikishi, si daemon. Haifungui port yoyote ya kusikiliza na haina huduma inayoendelea kwa muda mrefu, kwa hivyo hakuna systemd unit ya kuandika na hakuna port ya kufunga firewall kwa ajili ya wakala yenyewe. Uzuiaji unategemea akaunti ya mtumiaji na saraka ya mradi, ndiyo maana sehemu ya kwanza ya mwongozo huu ndiyo muhimu zaidi.

Sanduku linalozunguka bado linahitaji uangalizi wa kawaida, kwa sababu VPS ya uandishi wa msimbo bado ni seva ya umma: SSH ya ufunguo pekee huku root login ikiwa imezimwa, kama ilivyo katika kuimarisha SSH kwenye VPS, firewall ya default-deny, na masasisho ya mara kwa mara. Na kagua kile wakala anachozalisha. Soma diffs zake kabla ya kuzipush, kama vile unavyosoma pull request kutoka kwa mchangiaji mpya, kwa sababu wewe ndiye unayesambaza matokeo.

Mwisho, weka zana yenyewe ikiwa ya kisasa. OpenCode hutoa matoleo mapya mara kwa mara, na masasisho hubeba marekebisho muhimu kwa programu inayoendesha amri kwenye seva yako. Kusasisha hutumia njia ile ile uliyotumia kusakinisha: endesha tena hati ya usakinishaji kama mtumiaji opencode, au endesha sudo npm update -g opencode-ai ikiwa ulisakinisha kupitia npm, kisha thibitisha toleo jipya kwa opencode --version. Dakika moja ya matengenezo mara kwa mara ni nafuu kuliko kutatua tabia ambayo toleo la miezi kadhaa iliyopita limesharekebishwa.

FAQ

Je, OpenCode inaweza kutumia model ya ndani badala ya API inayolipiwa?

Ndiyo. OpenCode huchukulia seva yoyote inayooana na OpenAI kama mtoa huduma, kwa hivyo model inayotumiwa na Ollama kwenye VPS hiyo hiyo inafanya kazi: taja mtoa huduma katika opencode.json ukitumia baseURL ya ndani na jina la model kama linavyoripotiwa na Ollama. Changamoto ni vifaa (hardware), kwa sababu model inayofaa kwa kazi halisi ya uandishi wa code inahitaji kumbukumbu kubwa, kwa hivyo hakikisha seva ina ukubwa unaofaa kwa model hiyo kabla ya kuipakua.

Ninawezaje kuifanya OpenCode iendelee kufanya kazi baada ya kufunga laptop yangu?

Iendeshe ndani ya tmux kwenye VPS. Anzisha wakala (agent) katika session yenye jina kwa kutumia tmux new -s opencode, ondoka (detach) kwa kubonyeza Ctrl-b kisha d, na session itaendelea kufanya kazi kwenye seva baada ya muunganisho wako wa SSH kukatika. Unganisha tena wakati wowote kwa kutumia tmux attach -t opencode na mazungumzo pamoja na kazi yoyote inayoendelea yatakuwepo. Kuanzisha upya seva (reboot) kutafunga session hiyo, kwa hivyo anzisha session mpya baada ya reboot.

Je, ni salama kuruhusu OpenCode kuendesha amri kwenye VPS yangu?

Ni jambo linaloweza kudhibitiwa ikiwa utaiwekea mipaka. Ipe OpenCode mtumiaji maalum asiye na upendeleo (unprivileged user) asiye na haki za sudo, weka miradi yake kwenye git ili kila mabadiliko yaweze kutenduliwa, hifadhi API key kwenye faili lenye mode 600, na utumie wakala wake wa Plan kwa ajili ya kupitia faili bila kuyabadilisha (read-only) kabla ya kuruhusu wakala wa Build kubadilisha chochote. Wakala huyo ataweza tu kuharibu kile ambacho akaunti yake inamiliki, na sehemu nyingine ya seva itabaki salama.

Kuna tofauti gani kati ya OpenCode na Claude Code?

OpenCode ni ya chanzo huria (MIT) na haifungwi na mtoa huduma mmoja, ikiunganisha zaidi ya watoa huduma 75 wa model, ikiwemo zile za ndani, kupitia kiolesura kimoja. Claude Code ni wakala wa terminal wa Anthropic yenyewe, iliyojengwa kuzunguka model za Anthropic. Ikiwa unataka zana moja inayofanya kazi na watoa huduma wengi, au mfumo unaojiendesha kikamilifu (self-hosted) na model ya ndani, OpenCode ndiyo chaguo sahihi; zote hufanya kazi vizuri kwenye VPS ndani ya tmux kwa kutumia usanidi uleule wa mtumiaji asiye na haki za juu.