Cài OpenHands trên VPS bằng Docker an toàn

OpenHands là gì và rủi ro đầu tiên cần hiểu

OpenHands, trước đây có tên là OpenDevin, là một agent tự động hóa kỹ thuật phần mềm. Bạn giao cho nó một tác vụ bằng ngôn ngữ tự nhiên. Nó sẽ lập kế hoạch, viết code, chạy command, đọc output và lặp lại quy trình cho đến khi hoàn tất tác vụ. Bạn chạy nó trên server của mình bằng Docker và kết nối nó với một language model. Trên VPS, OpenHands trở thành một coding agent có thể làm việc khi bạn không có mặt.

Có một yếu tố phải định hướng toàn bộ cấu hình của bạn. OpenHands không chỉ đề xuất code mà còn chạy code. Để làm việc đó, container controller của nó mount Docker socket của host tại /var/run/docker.sock để có thể tạo sandbox container cho từng tác vụ. Bất kỳ tiến trình nào có thể truy cập Docker socket đều có thể khởi động một container mới và mount toàn bộ filesystem của host. Điều này có nghĩa là quyền truy cập socket về thực tế tương đương với quyền root trên máy. Vì vậy, hãy xem máy chạy OpenHands là một server thực thi code không đáng tin cậy, vì đó chính xác là chức năng của nó. Mọi lựa chọn hardening bên dưới đều xuất phát từ nguyên tắc này.

Bạn cần gì

Bạn cần một VPS chạy Ubuntu 24.04 với Docker Engine phiên bản gần đây, ít nhất 4 GB RAM và API key cho một language model (OpenAI, Anthropic hoặc Google), hoặc một model local được cung cấp bởi Ollama trên cùng VPS. OpenHands hỗ trợ hàng chục model backend, nên bạn có thể tự chọn. Nếu chưa từng thiết lập container, kiến thức cơ bản về Docker trên VPS sẽ bao quát những nội dung mà hướng dẫn này giả định bạn đã biết.

Cài đặt bằng Docker

OpenHands được phát hành dưới dạng 2 image: image ứng dụng mà bạn chạy và image agent-server mà ứng dụng pull về để chạy sandbox cho từng task. Chạy như sau, thay các tag bằng tag hiện tại trong tài liệu của dự án:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

Có 2 chi tiết giúp tránh mất cả giờ để tìm lỗi. Image ứng dụng và image agent-server cố ý dùng các số phiên bản khác nhau, vì vậy không được cố ghép chúng cho giống nhau: hãy dùng tag agent-server mà tài liệu chỉ định tương ứng với phiên bản ứng dụng của bạn. Ngoài ra, hãy chú ý đến -p 127.0.0.1:3000:3000 thay vì -p 3000:3000. Thay đổi duy nhất này quyết định Web UI chỉ có bạn truy cập được hay toàn bộ Internet đều truy cập được. Phần tiếp theo sẽ nói về điểm này.

Để Web UI không public Internet

OpenHands cung cấp giao diện trên port 3000. Giao diện này điều khiển một agent có thể chạy code, nên publish nó lên Internet sẽ cho bất kỳ ai tìm thấy nó một đường truy cập từ xa vào tiến trình thực thi command. Hãy bind giao diện vào loopback như run command ở trên, rồi truy cập từ laptop qua SSH tunnel:

ssh -L 3000:127.0.0.1:3000 you@your-vps

Sau đó mở http://127.0.0.1:3000 trên máy của bạn. Traffic đi qua SSH session hiện có, và không có service mới nào listening trên public Internet. Không phải agent nào cũng cần port: các session Claude Code trên cùng VPS trao đổi với nhau qua terminal, nên thứ duy nhất bạn cần expose là chính SSH. Bạn nên áp dụng cùng thói quen loopback và tunnel cho mọi agent dashboard tự host; truy cập UI scanning của open-kritt qua tunnel cũng hoạt động tương tự, chỉ khác là dùng port 5173. Nếu cần thiết lập lâu dài hơn, hãy đặt nó phía sau VPN. Dù dùng cách nào, hãy đặt firewall default-deny phía trước máy chủ để không vô tình expose dịch vụ nào, và nhớ rằng firewall chỉ áp dụng cho IPv4 sẽ vẫn để port đó mở trên IPv6. Đây chính là khoảng trống firewall trên IPv6 khiến rất nhiều người gặp sự cố.

Cô lập model key và credential của repository

OpenHands cần API key cho model và thường cần token để clone, push vào repository của bạn. Cả hai đều có thể phát sinh chi phí và hoạt động dưới danh nghĩa của bạn, vì vậy hãy xử lý chúng như password. Lưu chúng trong một file môi trường mà chỉ đúng account mới có thể đọc. Không đặt chúng trong lệnh chạy, vì chúng sẽ xuất hiện trong shell history và process list. Cũng không lưu chúng trong file bên trong git repository. Nếu lưu bản gốc trong password manager tự host, hãy harden cả server đó, vì điểm yếu của vault thường nằm ở admin token và file backup, không phải ở các item đã mã hóa, như phần harden Vaultwarden sẽ trình bày.

Chạy trên một máy chủ có thể bỏ đi

Vì controller phải giữ Docker socket, bạn không thể sandbox OpenHands hoàn toàn khỏi host của nó. Biện pháp giảm thiểu thực tế là cô lập bằng cách bố trí: chạy OpenHands trên một VPS riêng, không chứa dữ liệu hay dịch vụ quan trọng nào, thay vì chạy trên server đang đồng thời vận hành database hoặc website của bạn. Tạo snapshot trước khi bắt đầu, rồi rebuild từ snapshot đó thay vì tiếp tục tin cậy một máy đã chạy code do agent viết trong một tuần. Một VPS giá rẻ, dùng cho một mục đích duy nhất và có thể bỏ đi là nơi phù hợp để chạy OpenHands. Trong trường hợp này, placement là yếu tố duy nhất OpenHands thực sự cho phép bạn kiểm soát. Nếu bạn cũng muốn kiểm soát agent được phép làm bao nhiêu việc trước khi dừng lại để hỏi, permission modes của Claude Code cho thấy cơ chế kiểm soát thứ hai đó hoạt động như thế nào trên một server không có ai giám sát.

Gia cố máy chủ

Phần còn lại là các bước vệ sinh máy chủ tiêu chuẩn. Các bước này quan trọng hơn bình thường vì workload ở đây có mức rủi ro cao hơn. Tạo một user admin không có quyền đặc biệt thay vì làm việc bằng root, theo hướng dẫn chạy service bằng user không có quyền đặc biệt. Chuyển SSH sang chỉ xác thực bằng key. Sau đó chạy checklist bên dưới và lưu checklist ở nơi bạn sẽ nhìn thấy lại.

Để hiểu các thành phần thay vì chỉ chạy chúng, hãy xem tự xây dựng AI agent trên VPS. Nếu muốn dùng một platform cần ít code hơn, tự host Dify là cách bắt đầu dễ hơn.

FAQ

OpenHands có an toàn khi chạy trên server không?

Có thể an toàn nếu cẩn thận, nhưng rủi ro cao hơn một web app thông thường vì nó ghi và chạy code, đồng thời controller của nó giữ Docker socket của host, về cơ bản tương đương quyền root trên máy. Hãy chạy nó trên một VPS riêng, có thể hủy và tạo lại, không chứa dữ liệu quan trọng nào khác; giữ Web UI chỉ bind trên loopback phía sau SSH tunnel hoặc VPN; tách riêng các key của nó và harden máy chủ. Không chạy nó cùng các service quan trọng.

Vì sao OpenHands cần Docker socket?

OpenHands chạy mỗi task trong một sandbox container mới. Nó yêu cầu Docker daemon trên host tạo các container đó bằng cách mount /var/run/docker.sock vào controller. Việc này cho controller container quyền điều khiển Docker trên host, nên rất mạnh và có rủi ro. Vì vậy, phải xem chính host là máy chạy code không đáng tin cậy.

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

Có. OpenHands hỗ trợ model local được Ollama hoặc vLLM cung cấp. Vì vậy, bạn có thể chạy hoàn toàn self-hosted, không mất phí theo token và không phải đưa dữ liệu ra khỏi server. Bạn cần một máy có đủ memory cho một coding model đủ năng lực. Đây cũng là vấn đề sizing được đề cập trong hướng dẫn Ollama.

Có nên chạy OpenHands trên server chính không?

Không. Vì nó chạy code do agent tạo ra và giữ Docker socket, hãy chạy nó trên một VPS riêng, chỉ phục vụ một mục đích và sẵn sàng rebuild khi cần. Nếu chạy cùng database, website hoặc các service khác, một lỗi của agent hoặc bug trong OpenHands có thể truy cập những thứ mà nó không được phép chạm tới.