Як запустити OpenCode на VPS

Що таке OpenCode та що ви налаштовуєте

OpenCode — це open source AI agent для написання коду, розроблений для роботи в terminal. Ви запускаєте його всередині директорії проєкту; він зчитує ваш код, пропонує зміни, редагує файли та виконує команди через terminal user interface (TUI). Проєкт має ліцензію MIT, підтримує понад 75 провайдерів моделей і станом на середину 2026 року має приблизно 165,000 GitHub stars, що робить його найпопулярнішим open source coding agent. Щоб запустити OpenCode на VPS, необхідно встановити його під окремим непривілейованим користувачем, зберегти API key моделі у приватному файлі та запустити у tmux, щоб сесія зберігалася після розриву з'єднання. Цей посібник описує саме ці кроки у відповідному порядку.

Важливе зауваження щодо назв. Канонічний репозиторій — anomalyco/opencode, який підтримує команда Anomaly (раніше відома як SST); раніше проєкт розміщувався за адресою sst/opencode. На GitHub також існує старий сторонній репозиторій під назвою opencode-ai/opencode, тому переконайтеся, що ви читаєте документацію саме потрібного проєкту. Офіційний сайт — opencode.ai.

Навіщо запускати OpenCode на VPS

Сесія агента програмування триває довго. OpenCode може витрачати багато хвилин на рефакторинг або запуск тестів. Якщо агент працює на ноутбуці, закриття кришки або розрив Wi-Fi перерве сесію під час виконання завдання. На VPS у середовищі tmux агент продовжує роботу після вашого відключення. Ви можете підключитися пізніше, щоб переглянути результат. Це той самий підхід, що і в running Claude Code on a VPS with tmux. Перенесення агента з ноутбука на VPS — це головний спосіб покращити зручність роботи.

Друга причина — розташування. VPS знаходиться поруч із кодом, який ви розгортаєте: репозиторієм, інструментами збірки, тестовою базою даних та часто зі staging-середовищем. Агенту, який редагує код і запускає тести, найкраще працювати на машині, де ці тести фактично виконуються. Оскільки сервер належить вам, ви можете спеціально налаштувати для агента ізольоване середовище, про що йдеться у наступному розділі.

Якщо ви ще обираєте інструмент, running a coding AI agent on a VPS порівнює різні рішення, включаючи Aider та Goose.

Надайте OpenCode окремого користувача

Ось реальний стан справ: агент для написання коду редагує файли та виконує команди. Це його основна функція, але це також і ризик. OpenCode виконуватиме збірки, тести та будь-які shell-команди, які знадобляться для виконання завдання. Судження моделі є точним, але не ідеальним. Права облікового запису, під яким працює агент, визначають межі можливих збитків від помилкової команди. Не запускайте агент як root і не використовуйте того самого користувача, який адмініструє сервер.

На відміну від фонових агентів, OpenCode є інтерактивним, тому його користувачеві потрібні реальна shell та домашня директорія:

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

Зберігайте проєкти для роботи у /home/opencode, клоновані цим користувачем. Не надавайте цьому обліковому запису прав sudo. Якщо агент виконає деструктивну команду, він зможе пошкодити лише те, що належить цьому конкретному користувачу. Це той самий принцип, що й у running services as an unprivileged user. Також працюйте всередині git-репозиторію, оскільки репозиторій перетворить будь-яку помилку редагування на git revert замість безповоротної втрати даних.

Встановлення OpenCode

Проєкт передбачає два способи встановлення. Використання скрипта встановлення є найшвидшим методом. При запуску скрипта від імені користувача opencode всі файли зберігаються в домашньому каталозі цього користувача:

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

Тут діє стандартне правило curl | bash: спочатку завантажте скрипт на сервер, перевірте його вміст, а потім запускайте. Після встановлення відкрийте нову сесію shell, щоб зміни у PATH набрали чинності, а потім перевірте відповіді бінарного файлу:

opencode --version

Якщо ви віддаєте перевагу менеджеру пакетів і Node.js уже встановлено в системі, метод npm встановить цей інструмент для всіх користувачів. Це додасть бінарний файл opencode до PATH кожного користувача:

sudo npm install -g opencode-ai

В обох випадках перевірка однакова: opencode --version виведе номер версії. Якщо після встановлення скрипта ви бачите command not found, це означає, що поточна сесія shell ще не оновила PATH. У такому разі вийдіть із системи та увійдіть знову під користувачем opencode.

Збережіть API key у приватному файлі

OpenCode потребує ключ для обраного провайдера моделей. Цей ключ може витрачати ваші кошти, тому ставтеся до нього як до пароля. Створіть файл із правами доступу 600, який може читати лише користувач opencode. Зберігайте ключ у файлі, а не в командному рядку, щоб він не потрапив у історію shell:

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

Запишіть у файл змінну вашого провайдера, наприклад ANTHROPIC_API_KEY=... або відповідну для вашого провайдера, оскільки OpenCode використовує стандартні змінні середовища провайдерів. Завантажте файл у ваш shell перед запуском агента:

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

OpenCode також має альтернативний інтерактивний спосіб: команда /connect у TUI допоможе налаштувати провайдера та збереже облікові дані у файлі ~/.local/share/opencode/auth.json у домашній директорії користувача. Якщо ви використовуєте цей спосіб, перевірте приватність файлу за допомогою chmod 600 ~/.local/share/opencode/auth.json. Обидва методи запобігають потраплянню ключа в історію команд; оберіть один спосіб і дотримуйтесь його.

Запуск OpenCode у tmux

tmux робить налаштування VPS корисним, оскільки сесія tmux продовжує працювати після розриву SSH-з'єднання. Запустіть її, перейдіть до папки проєкту та запустіть агент:

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

Має відкритися TUI з рядком введення внизу та назвою вашого проєкту в інтерфейсі. Введіть завдання звичайною мовою, і агент почне читати файли та пропонувати зміни. Щоб вийти, від'єднайтеся за допомогою Ctrl-b, потім d; агент продовжить роботу, навіть якщо ноутбук буде закритий. Щоб приєднатися знову, виконайте:

tmux attach -t opencode

Сесія, діалог та всі поточні завдання залишаються на тих самих місцях. Це працює після розриву зв'язку, але не після перезавантаження сервера. Після перезавантаження потрібно створити нову сесію tmux тим самим способом.

Підключення до моделі

OpenCode не залежить від конкретного провайдера. Використання AI SDK та каталогу Models.dev дозволяє підтримувати понад 75 провайдерів. Один і той самий інструмент працює з Anthropic, OpenAI, Google та десятками інших сервісів, включаючи локальні сервери. Найшвидший спосіб — команда /connect у TUI, яка виводить список провайдерів та дозволяє налаштувати облікові дані. Для створення конфігурації, яку можна зафіксувати в репозиторії та відтворити, додайте opencode.json у корінь проєкту та вкажіть модель як provider/model-id:

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

Локальна модель налаштовується через той самий файл, оскільки будь-який сервер, сумісний з OpenAI, можна оголосити як провайдера. Якщо ви використовуєте Ollama на тому ж VPS, конфігурація вказує на його локальний API, а назва моделі відповідає значенню, яке ollama list відображає у вашій системі:

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

З першого дня варто прийняти одну стандартну практику. OpenCode містить двох агентів, перемикання між якими здійснюється клавішею Tab: Build (агент за замовчуванням з повним доступом) та Plan (агент, який забороняє внесення змін). Почніть нове завдання в режимі Plan, дозвольте йому прочитати код і запропонувати підхід, і перемикайтеся на Build лише після погодження плану. Використання режиму лише для читання на сервері — це надійний спосіб уникнути помибок.

Межі впливу

Агент для написання коду не є пасивним, тому чітко визначте можливості та обмеження цього налаштування. Він може пошкодити файли: користувач opencode володіє лише власним домашнім каталогом, тому редагування та видалення обмежені цими межами. Він може призвести до витоку облікових даних: ключ зберігається в одному файлі з правами 600 в одному обліковому записі. Він не обмежує дії, на які обліковий запис має право: якщо в директорії проєкту містяться облікові дані для розгортання (production deploy), агент зможе їх використати; тримайте такі дані повністю поза межами облікового запису агента.

На відміну від шлюзових агентів, таких як OpenClaw, OpenCode — це інтерактивна термінальна програма, а не демон. Вона не відкриває порт для прослуховування і не є довготривалим сервісом, тому для самого агента не потрібно створювати unit для systemd або налаштовувати firewall для портів. Обмеження забезпечуються обліковим записом користувача та директорією проєкту, тому перший розділ цього посібника є найважливішим.

Сервер все одно потребує стандартного догляду, оскільки VPS для кодування залишається публічним сервером: SSH лише за ключами з вимкненим входом для root, як описано в SSH hardening on a VPS, firewall з політикою default-deny та регулярні оновлення. Також перевіряйте результат роботи агента. Переглядайте його diffs перед тим, як робити push, так само як ви переглядаєте pull request від нового контриб'ютора, адже саме ви розгортаєте результат.

Нарешті, підтримуйте сам інструмент у актуальному стані. OpenCode часто випускає релізи, а оновлення містять виправлення, важливі для програми, що виконує команди на вашому сервері. Оновлення виконується тим самим способом, яким здійснювалося встановлення: запустіть інсталяційний скрипт від імені користувача opencode або запустіть sudo npm update -g opencode-ai, якщо ви встановлювали через npm, а потім перевірте нову версію за допомогою opencode --version. Хвилина технічного обслуговування час від часу дешевша, ніж налагодження помилок, які вже були виправлені у версії місячної давнини.

FAQ

Чи може OpenCode використовувати локальну модель замість платного API?

Так. OpenCode розглядає будь-який сервер, сумісний з OpenAI, як провайдера. Модель, що запускається через Ollama на тому ж VPS, буде працювати: вкажіть провайдера у opencode.json за допомогою локального baseURL та назви моделі, яку повертає Ollama. Обмеження полягає у залізі, оскільки моделі для професійного програмування потребують значного обсягу пам'яті. Підберіть характеристики сервера під модель перед її завантаженням.

Як забезпечити роботу OpenCode після закриття ноутбука?

Запускайте програму всередині tmux на VPS. Запустіть агент уменованій сесії за допомогою tmux new -s opencode, від'єднайтеся за допомогою Ctrl-b, потім d. Сесія продовжуватиме працювати на сервері після розриву SSH-з'єднання. У будь-який час можна під'єднатися знову за допомогою tmux attach -t opencode — діалог та поточне завдання збережуться. Перезавантаження сервера завершує сесію, тому після перезавантаження потрібно запустити нову.

Чи безпечно дозволяти OpenCode виконувати команди на моєму VPS?

Це безпечно, якщо обмежити права доступу. Надайте OpenCode окремого непривілейованого користувача без прав sudo. Зберігайте проєкти в git, щоб кожну зміну можна було скасувати. Зберігайте API key у файлі з правами 600. Використовуйте агент Plan для первинного аналізу лише для читання, перш ніж дозволяти агенту Build вносити зміни. У такому разі агент зможе пошкодити лише ті файли, які належать його власному обліковому запису, а решта сервера залишиться недоступною.

Яка різниця між OpenCode та Claude Code?

OpenCode — це open source (MIT) інструмент, незалежний від провайдера. Він підтримує понад 75 провайдерів моделей, включаючи локальні, через єдиний інтерфейс. Claude Code — це термінальний агент від Anthropic, розроблений для моделей Anthropic. Якщо вам потрібен один інструмент для багатьох провайдерів або повністю автономний стек із локальною моделлю, підійде OpenCode. Обидва інструменти добре працюють на VPS у tmux з налаштуванням через непривілейованого користувача.