Cách chạy OpenCode trên VPS an toàn với tmux

OpenCode là gì và bạn sẽ thiết lập những gì

OpenCode là một AI coding agent mã nguồn mở dành cho terminal. Bạn khởi động nó trong thư mục dự án. OpenCode đọc code, đề xuất thay đổi, chỉnh sửa file và chạy command thông qua terminal user interface (TUI). OpenCode được cấp phép theo MIT, kết nối với hơn 75 model provider và có khoảng 165,000 GitHub star vào giữa năm 2026. Đây là open source coding agent có nhiều star nhất hiện nay. Để chạy OpenCode trên VPS, bạn cài đặt nó dưới một user không có đặc quyền riêng, lưu model API key trong một file riêng tư và khởi động nó bên trong tmux để session vẫn tồn tại khi kết nối bị ngắt. Guide này thực hiện đúng các bước đó theo thứ tự.

Một lưu ý về tên gọi sẽ giúp tránh nhầm lẫn. Repository chính thức là anomalyco/opencode, do team Anomaly duy trì (trước đây có tên là SST), và dự án từng được lưu trữ tại sst/opencode. Trên GitHub cũng có một repository không liên quan tên opencode-ai/opencode, vì vậy hãy kiểm tra để chắc chắn bạn đang đọc tài liệu của đúng dự án. Website chính thức là opencode.ai.

Vì sao nên chạy OpenCode trên VPS

Một phiên làm việc với coding agent thường kéo dài. OpenCode có thể mất nhiều phút để xử lý một đợt refactor hoặc chạy một test suite. Nếu chạy trên laptop, việc đóng nắp máy hoặc mất kết nối Wi-Fi sẽ làm phiên bị dừng giữa chừng. Khi chạy agent trên VPS bên trong tmux, agent vẫn tiếp tục làm việc sau khi bạn ngắt kết nối. Sau đó, bạn có thể kết nối lại để xem agent đã thực hiện những gì. Đây cũng là cách chạy Claude Code trên VPS với tmux, và là lợi ích lớn nhất về trải nghiệm khi chuyển agent khỏi laptop.

Lý do thứ hai là vị trí. VPS ở gần code bạn deploy: repository, công cụ build, test database và thường cả môi trường staging đã nằm trên đó hoặc ở máy kế bên. Agent chỉnh sửa code và chạy test sẽ hoạt động hiệu quả nhất trên chính máy đang chạy các test đó. Vì đây là server do bạn kiểm soát, bạn có thể chủ động cấp cho agent một môi trường được cô lập. Phần tiếp theo sẽ thực hiện việc này.

Nếu bạn vẫn đang chọn công cụ, chạy coding AI agent trên VPS sẽ so sánh nhiều lựa chọn hơn, bao gồm Aider và Goose.

Cấp cho OpenCode một user riêng

Điểm cần nói rõ là: coding agent chỉnh sửa file và chạy command. Đó là nhiệm vụ của nó, đồng thời cũng là rủi ro. OpenCode sẽ chạy build, test và mọi shell command mà task có vẻ cần. Khả năng phán đoán của model tốt nhưng không hoàn hảo. User mà agent chạy dưới quyền sẽ giới hạn tối đa phạm vi mà một command nguy hiểm có thể tác động đến. Vì vậy, không chạy OpenCode bằng root và không chạy bằng user đang quản trị server.

Khác với background agent, OpenCode hoạt động tương tác. Vì vậy, user của nó cần có shell thực và home directory:

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

Đặt các project mà bạn muốn OpenCode xử lý dưới /home/opencode và clone chúng bằng user đó. Không cấp quyền sudo cho account này. Nếu agent chạy một command phá hủy dữ liệu, command đó chỉ có thể phá hủy những gì account này sở hữu. Đây cũng là nguyên tắc giống như chạy service bằng user không có đặc quyền. Đồng thời, hãy làm việc trong một git repository. Repository biến mọi chỉnh sửa sai thành một git revert thay vì mất dữ liệu.

Cài đặt OpenCode

Tài liệu của dự án nêu 2 cách cài đặt. Script cài đặt là cách nhanh nhất. Chạy script với user opencode sẽ giữ mọi thứ trong home của user đó:

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

Thói quen curl | bash thông thường cũng áp dụng ở đây như mọi nơi khác: trên server quan trọng, trước tiên hãy download script, đọc script, rồi mới chạy. Sau khi cài đặt, hãy mở shell mới để thay đổi PATH do installer thực hiện có hiệu lực, rồi kiểm tra binary có trả về kết quả hay không:

opencode --version

Nếu thích dùng package manager và Node.js đã có trên máy, cách cài qua npm sẽ cài cùng công cụ đó system-wide. Khi đó binary opencode có trong PATH của mọi user:

sudo npm install -g opencode-ai

Dù dùng cách nào, lệnh kiểm tra vẫn giống nhau: opencode --version sẽ in ra số version. Nếu thấy command not found sau khi cài bằng script, nghĩa là shell hiện tại chưa đọc PATH mới. Hãy logout rồi login lại bằng user opencode.

Đặt API key trong file riêng tư

OpenCode cần key cho model provider bạn sử dụng. Key đó có thể tiêu tiền của bạn, nên hãy bảo vệ nó như password. Tạo một file chỉ user opencode có thể đọc, với mode 600. Lưu key trong file đó thay vì nhập vào command, vì key có thể bị ghi vào shell history:

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

Đặt biến của provider vào file, ví dụ ANTHROPIC_API_KEY=... hoặc biến tương đương của provider đó. OpenCode sẽ đọc các biến môi trường chuẩn của provider. Load file vào shell trước khi khởi động agent:

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

OpenCode cũng có cách tương tác khác: command /connect trong TUI sẽ hướng dẫn bạn thêm provider và lưu credential vào ~/.local/share/opencode/auth.json trong home directory của user. Nếu dùng cách này, hãy xác nhận file là private bằng chmod 600 ~/.local/share/opencode/auth.json. Cả hai cách đều giữ key khỏi command line. Hãy chọn một cách và sử dụng nhất quán.

Khởi động OpenCode trong tmux

tmux là thành phần khiến việc thiết lập VPS trở nên đáng làm, vì một tmux session vẫn tiếp tục chạy khi kết nối SSH của bạn kết thúc. Hãy tạo một session, chuyển đến project của bạn rồi khởi động agent:

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

Bạn sẽ thấy TUI mở ra, có prompt ở phía dưới và tên project trong giao diện. Hãy giao nhiệm vụ bằng ngôn ngữ thông thường. Agent sẽ bắt đầu đọc file và đề xuất thay đổi. Khi muốn rời đi, hãy detach bằng Ctrl-b rồi d. Agent vẫn tiếp tục làm việc ngay cả khi bạn đóng laptop. Sau đó reattach bằng:

tmux attach -t opencode

session, cuộc trò chuyện và mọi task đang chạy vẫn ở đúng trạng thái trước đó. Cách này chịu được việc bạn mất kết nối, nhưng không chịu được server reboot. Sau khi reboot, bạn cần tạo một tmux session mới theo cách tương tự. Bạn cũng có thể mở cửa sổ tmux thứ hai và chạy một agent khác song song với agent đầu tiên. Tuy nhiên, các OpenCode session độc lập với nhau, trong khi các Claude Code session trên cùng một máy có thể gửi message cho nhau. Đây là một cách khác để chia một công việc thành hai phần.

Trỏ đến một model

OpenCode không phụ thuộc vào provider cụ thể. Công cụ này dùng AI SDK và catalog Models.dev để hỗ trợ hơn 75 provider, nên cùng một công cụ có thể làm việc với Anthropic, OpenAI, Google và hàng chục provider khác, bao gồm cả local server. Cách nhanh nhất là dùng lệnh /connect trong TUI. Lệnh này liệt kê các provider và xử lý credential. Nếu cần cấu hình có thể commit và tái tạo, hãy tạo file opencode.json ở thư mục gốc của project và đặt model bằng provider/model-id:

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

Bạn cũng có thể dùng local model thông qua cùng file này, vì mọi OpenAI-compatible server đều có thể khai báo làm provider. Nếu chạy model bằng Ollama trên cùng VPS, cấu hình sẽ trỏ đến local API của Ollama. Tên model là giá trị mà ollama list hiển thị trên máy của bạn:

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

Có một thói quen tích hợp sẵn mà bạn nên áp dụng ngay từ đầu. OpenCode cung cấp 2 agent và bạn chuyển đổi giữa chúng bằng phím Tab: Build là agent mặc định với toàn quyền truy cập, còn Plan vô hiệu hóa khả năng thực hiện thay đổi. Hãy bắt đầu task mới trong Plan, để agent đọc code và đề xuất cách làm, rồi chỉ chuyển sang Build khi bạn đồng ý với kế hoạch. Trên server, kiểm tra read-only trước là một biện pháp an toàn ít tốn kém. Claude Code biểu diễn cùng quyết định này bằng permission mode thay vì agent. Bạn nên đọc việc chuyển auto mode thành mặc định của Claude Code nếu chạy cả 2 công cụ, vì mode mà một session khởi động sẽ quyết định agent không được giám sát có thể thay đổi bao nhiêu.

Phạm vi ảnh hưởng, nói thẳng

Coding agent không thụ động, vì vậy cần nói rõ setup này bảo vệ được gì và không bảo vệ được gì. Nó có giới hạn thiệt hại đối với file: user opencode chỉ sở hữu home directory của chính mình và không sở hữu gì khác, nên việc chỉnh sửa và xóa file sẽ dừng ở ranh giới đó. Nó vẫn có thể làm lộ credential: key nằm trong một file có mode 600, thuộc về một account duy nhất. Nó không giới hạn những gì account đó được phép thực hiện, nên nếu project directory chứa credential để deploy production, agent có thể sử dụng chúng; hãy để các credential đó hoàn toàn bên ngoài account của agent.

Khác với gateway agent như OpenClaw, OpenCode là một chương trình terminal tương tác, không phải daemon. Nó không mở listening port và không có service chạy lâu dài, nên không có systemd unit nào cần tạo và cũng không có port nào cần cấu hình firewall riêng cho agent. User account và project directory là lớp containment của nó. Vì vậy, phần đầu tiên của hướng dẫn này là phần quan trọng nhất.

Phần máy chủ xung quanh vẫn cần được bảo vệ theo cách tiêu chuẩn, vì coding VPS vẫn là public server: SSH chỉ dùng key và tắt root login, như trong Hardening SSH trên VPS, firewall mặc định deny, và cập nhật định kỳ. Đồng thời, hãy review những gì agent tạo ra. Đọc diff trước khi push, giống như khi review pull request từ một contributor mới, vì chính bạn là người deploy kết quả đó.

Cuối cùng, hãy luôn cập nhật chính tool này. OpenCode thường xuyên phát hành bản mới, và các bản cập nhật mang theo những bản sửa lỗi quan trọng đối với một chương trình chạy command trên server của bạn. Cập nhật bằng đúng cách đã dùng khi cài đặt: chạy lại install script với user opencode, hoặc chạy sudo npm update -g opencode-ai nếu cài qua npm, sau đó xác nhận version mới bằng opencode --version. Thỉnh thoảng dành một phút để bảo trì sẽ rẻ hơn việc debug một vấn đề mà bản build đã cũ hàng tháng từng được sửa rồi.

FAQ

OpenCode có thể dùng model local thay cho API trả phí không?

Có. OpenCode coi mọi server tương thích với OpenAI là một provider, nên model được Ollama cung cấp trên cùng VPS cũng hoạt động: khai báo provider trong opencode.json cùng với baseURL local và tên model do Ollama báo cáo. Điểm cần lưu ý là phần cứng, vì model đủ tốt cho công việc lập trình thực tế cần nhiều memory. Hãy chọn cấu hình server phù hợp với model trước khi tải model xuống.

Làm cách nào để OpenCode tiếp tục chạy sau khi tôi đóng laptop?

Chạy OpenCode trong tmux trên VPS. Khởi động agent trong một session có tên bằng tmux new -s opencode, detach bằng Ctrl-b rồi d. Session vẫn tiếp tục chạy trên server sau khi kết nối SSH kết thúc. Bạn có thể attach lại bất kỳ lúc nào bằng tmux attach -t opencode; conversation và mọi task đang chạy vẫn còn đó. Reboot server sẽ kết thúc session, nên hãy tạo session mới sau khi reboot.

Cho OpenCode chạy command trên VPS có an toàn không?

Có thể kiểm soát được nếu bạn cô lập nó. Cấp cho OpenCode một user không có đặc quyền và không có sudo, lưu các project trong git để có thể hoàn tác mọi chỉnh sửa, lưu API key trong file có mode 600, rồi dùng Plan agent để kiểm tra chỉ đọc trước khi cho Build agent thay đổi bất cứ thứ gì. Khi đó agent chỉ có thể gây hại cho những tài nguyên thuộc account của nó, còn phần còn lại của server vẫn nằm ngoài quyền truy cập.

OpenCode khác Claude Code ở điểm nào?

OpenCode là phần mềm mã nguồn mở (MIT) và không phụ thuộc provider cụ thể, kết nối với hơn 75 model provider, bao gồm cả provider local, thông qua một interface. Claude Code là terminal agent của Anthropic, được xây dựng cho các model của Anthropic. Nếu bạn muốn dùng một tool với nhiều provider, hoặc một stack tự host hoàn toàn có model local, OpenCode phù hợp hơn. Cả hai đều chạy tốt trên VPS bên trong tmux với cùng cách thiết lập user không có đặc quyền.