Cách triển khai Agentbox và chạy Claude Code hoặc Codex từ trình duyệt

Agentbox là gì?

Agentbox là môi trường tự lưu trữ để chạy Claude Code và Codex CLI từ trình duyệt. Công cụ này kết hợp trò chuyện AI, terminal, tệp dự án, xem xét Git, quản trị tài khoản và theo dõi mức sử dụng trong các không gian làm việc cố định được lưu trữ trên máy chủ của bạn.

Máy chủ được phân phối dưới dạng một tệp nhị phân Go duy nhất với frontend TypeScript được nhúng. Công cụ lưu trạng thái ứng dụng và lịch sử trò chuyện trong SQLite, đồng thời sử dụng các container Docker để cô lập không gian làm việc lập trình. Các thư mục cố định bảo toàn tệp dự án, cấu hình thư mục người dùng và tài nguyên dùng chung độc lập với vòng đời của container.

Agentbox đặc biệt hữu ích khi bạn muốn bắt đầu một tác vụ lập trình trên thiết bị này và tiếp tục trên thiết bị khác mà không cần xây dựng lại môi trường. Bạn có thể sử dụng Web chat dạng streaming cho công việc theo tác vụ hoặc mở terminal trên trình duyệt để làm việc trực tiếp với Claude Code hoặc Codex CLI gốc.

Tính năng chính

• Không gian làm việc cố định: Tệp dự án, cấu hình thư mục người dùng, tệp dùng chung và lịch sử trò chuyện vẫn được lưu trên máy chủ của bạn.
• Hai giao diện tác vụ: Chuyển đổi giữa trò chuyện trên trình duyệt và các công cụ dòng lệnh gốc.
• Quy trình phân phối tích hợp: Tải lên hoặc sao chép một dự án, giao nhiệm vụ, kiểm tra tệp, xem xét các thay đổi Git rồi commit hoặc tải xuống kết quả.
• Kho tài khoản tập trung: Quản trị viên có thể cấu hình gói đăng ký OAuth Claude và Codex, khóa API, endpoint chuyển tiếp, phạm vi truy cập và proxy thoát.
• Bản ghi sử dụng và chi phí: Lọc mức sử dụng theo người dùng, mô hình và thời gian, đồng thời kiểm tra token, nguồn định giá, độ trễ và chi phí được ghi nhận.
• Tài nguyên có thể tái sử dụng: Mỗi người dùng nhận một thư mục dùng chung được mount tại /shared trong tất cả không gian làm việc của họ. Mẫu thư mục người dùng, skill Claude và cấu hình MCP cũng được hỗ trợ.
• Truy cập mạng riêng tùy chọn: Ứng dụng khách abox-link có thể cung cấp cho các không gian làm việc lưu trữ trên đám mây quyền truy cập vào những kho mã, cơ sở dữ liệu và dịch vụ được cho phép rõ ràng.
• Giao diện tương thích: Bảng điều khiển hỗ trợ liên kết sâu, giao diện sáng và tối cùng bố cục trên thiết bị di động.

Tìm hiểu kiến trúc

Trình duyệt của bạn kết nối với máy chủ Agentbox qua HTTP hoặc HTTPS và các kết nối WebSocket. Máy chủ điều khiển các container không gian làm việc thông qua Docker API cục bộ và lưu các bản ghi ứng dụng trong SQLite. Mỗi không gian làm việc có một container riêng cùng các thư mục cố định.

Một không gian làm việc có thể chứa nhiều chuỗi trò chuyện, nhưng mỗi lần chỉ một lượt Web chat chạy trong không gian làm việc đó. Các vị trí cố định chính là /workspace, /home/agent và /shared. Các tệp cần tồn tại sau khi thay thế container nên được lưu tại một trong các vị trí này.

Quan trọng: Tệp cố định không đồng nghĩa với tiến trình cố định. Việc kết nối lại sau khi mạng terminal bị gián đoạn có thể khôi phục một phiên tmux, nhưng việc dừng hoặc xây dựng lại container sẽ chấm dứt các tiến trình đang chạy.

Điều kiện tiên quyết

Phương pháp cài đặt nhanh nhất dành cho máy chủ Linux sử dụng systemd. Các gói phát hành hỗ trợ Linux x86_64 và arm64.

• Ubuntu 22.04 trở lên hoặc Debian 12 trở lên có thể được tự động cài đặt các dependency còn thiếu và Docker.
• Các bản phân phối Linux khác cần Python 3.9 trở lên, Git, curl, chứng chỉ CA, dữ liệu múi giờ và Docker Engine cục bộ.
• Lần xây dựng image không gian làm việc đầu tiên cần truy cập các registry container, kho gói Debian và npm.
• Để truy cập từ xa, cổng TCP 8180 phải được cho phép qua tường lửa máy chủ hoặc security group, trừ khi bạn sử dụng chuyển tiếp SSH hoặc reverse proxy.

Bản cài đặt dựng sẵn không yêu cầu Go hoặc Node.js trên máy chủ.

Cài đặt Agentbox bằng trình cài đặt bản phát hành

1. Chạy trình cài đặt

Kết nối với máy chủ Linux và chạy:

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash

Theo mặc định, trình cài đặt chọn bản phát hành ổn định mới nhất. README xác định v0.1.5 là bản ổn định hiện tại. Để cố định phiên bản này, hãy sử dụng:

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --version v0.1.5

Quá trình cài đặt xác minh gói phát hành, xây dựng image không gian làm việc với các phiên bản công cụ được cố định, tạo cấu hình, sinh mật khẩu quản trị viên ngẫu nhiên và khởi động agentbox.service. Lần xây dựng image đầu tiên có thể mất vài phút.

2. Mở bảng điều khiển

Khi cài đặt hoàn tất, hãy ghi lại mật khẩu quản trị viên được in trong terminal. Mở địa chỉ sau và thay phần giữ chỗ bằng địa chỉ máy chủ:

http://YOUR_SERVER_IP:8180

Đăng nhập bằng tên người dùng boxadmin và mật khẩu đã tạo. Hãy cấu hình HTTPS trước khi mở Agentbox cho hoạt động công khai lâu dài.

3. Giới hạn Agentbox thông qua reverse proxy

Nếu Agentbox chỉ nên chấp nhận các kết nối cục bộ, hãy thêm tùy chọn listen trong quá trình cài đặt:

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --listen 127.0.0.1:8180

Sau đó, bạn có thể đặt một reverse proxy HTTPS có hỗ trợ WebSocket phía trước dịch vụ. Bản cài đặt phát hành lưu cấu hình tại /etc/agentbox và dữ liệu ứng dụng tại /var/lib/agentbox.

Cấu hình tài khoản Claude hoặc Codex

Sau khi đăng nhập, mở Cài đặt hệ thống → Kho tài khoản, hiện được hiển thị trong giao diện tiếng Trung là 系统设置 → 账号池. Thêm tài khoản Claude hoặc Codex.

Agentbox hỗ trợ các phương thức kết nối sau:

• Gói thuê bao Claude: Chọn OAuth gói thuê bao và dán mã ủy quyền.
• Gói thuê bao Codex: Chọn OAuth gói thuê bao và dán toàn bộ URL callback.
• Tài khoản API hoặc relay: Nhập endpoint và khóa của nhà cung cấp. Relay Codex phải tuân theo giao thức mà nhà cung cấp yêu cầu.

Đặt tên tài khoản dễ nhận biết, proxy egress nếu cần và phạm vi truy cập. Tài khoản có thể khả dụng cho tất cả người dùng, người dùng được chọn hoặc chỉ quản trị viên. Quản trị viên có thể sử dụng mọi tài khoản đã cấu hình.

Người dùng workspace có quyền truy cập terminal có thể đọc thông tin xác thực được cung cấp cho các công cụ dòng lệnh bên trong container của họ. Vì vậy, các nhóm tài khoản dùng chung chỉ nên được giới hạn cho những người dùng đáng tin cậy. Việc thu hồi quyền truy cập sẽ ngăn các thao tác mới và đồng bộ thông tin xác thực, nhưng để thu hồi hoàn toàn, bạn cũng có thể cần dừng các container bị ảnh hưởng và thay đổi thông tin xác thực ở hệ thống nguồn.

Tạo workspace đầu tiên

1. Tạo một workspace và đặt tên mô tả.
2. Chọn Claude Code hoặc Codex CLI làm agent.
3. Chọn tài khoản mà người dùng của bạn được phép sử dụng.
4. Nhập dự án bằng cách tải lên qua Files hoặc sao chép dự án trong Terminal.
5. Mở Chat và gửi một tác vụ lập trình cụ thể.
6. Kiểm tra các tệp đã chỉnh sửa và xem Git diff trong Changes.
7. Commit các thay đổi cục bộ hoặc tải xuống các tệp dự án.

Tải lên và kiểm tra tệp dự án

Giao diện Files cung cấp cây thư mục, tính năng tải lên, chỉnh sửa, xem trước và tải xuống kho lưu trữ cho các thư mục dự án và thư mục dùng chung. Trình xem mã nguồn có số dòng, tô sáng cú pháp, điều hướng theo dòng và cột, tô sáng dòng hiện tại và chế độ toàn màn hình.

Các thao tác tệp trên web sử dụng handle thư mục bị giới hạn và không đi theo liên kết tượng trưng. Tệp tải lên được xác thực trong các thư mục tạm thời, còn thao tác lưu của trình chỉnh sửa sử dụng cơ chế thay thế nguyên tử. Các công cụ dòng lệnh bên trong container vẫn có thể sử dụng các liên kết do template cung cấp.

Sao chép repository từ terminal

Mở Terminal và chạy các lệnh shell thông thường. Ví dụ:

cd /workspace
git clone https://github.com/OWNER/PROJECT.git
cd PROJECT
git status

Agentbox tích hợp các CLI agent gốc và những công cụ phát triển phổ biến trong image workspace. Các phiên terminal sử dụng tmux, cho phép bạn kết nối lại sau khi trình duyệt hoặc mạng bị ngắt kết nối.

Giao nhiệm vụ trong Web chat

Mở Chat và mô tả thay đổi cần thực hiện, các ràng buộc liên quan và cách xác thực bạn mong đợi. Ví dụ:

Inspect this project and add input validation to the user registration endpoint. Preserve the existing API response format, add tests for invalid email addresses, and run the relevant test suite.

Chat hỗ trợ lựa chọn model và mức độ suy luận. Mỗi phản hồi ghi lại thời gian, model, ảnh chụp cài đặt và chi phí. Claude chạy các lượt xử lý headless dạng streaming. Codex ưu tiên tích hợp app-server và chuyển sang chế độ thực thi nếu bắt tay thất bại.

Kiểm tra và bàn giao kết quả

Sau khi agent hoàn tất, mở Changes để kiểm tra các tệp đã sửa đổi và diff được tô màu. Xem toàn bộ tệp khi diff không cung cấp đủ ngữ cảnh.

Các commit trên web là commit cục bộ và không tự động đẩy lên repository từ xa. Chúng cũng không chạy Git hook hoặc ký commit. Sử dụng terminal khi cần hook hoặc commit đã ký.

Agentbox cũng cung cấp tính năng quản lý Git cho kết nối repository, sao chép, fetch, pull fast-forward, push có xem trước, thao tác nhánh và tạo pull request hoặc merge request trên GitHub hoặc GitLab. Kết nối repository có thể sử dụng token HTTPS hoặc khóa riêng SSH.

Build và chạy từ mã nguồn

Sử dụng quy trình mã nguồn khi bạn dự định sửa đổi Agentbox hoặc đóng góp cho dự án. Môi trường build được tài liệu hóa sử dụng Linux với Docker, Go 1.26.6 hoặc toolchain tự động tương thích, Git, Python 3, curl, iproute2 và OpenSSL. Chỉ cần Node.js 22 và npm khi chỉnh sửa console TypeScript chính.

1. Sao chép và build

git clone https://github.com/devilcoolyue/agentbox.git
cd agentbox

go build -o agentbox ./cmd/agentbox
./scripts/build-image.sh

Người chạy quá trình build image cần có quyền truy cập Docker. Khi khởi động, máy chủ cũng phải đặt quyền sở hữu thư mục được mount thành 1000:1000; service systemd được cung cấp chạy với quyền root.

2. Tạo cấu hình

cp config.example.json config.json
openssl rand -hex 24

Sao chép giá trị ngẫu nhiên được tạo vào auth_token. Để kiểm thử ban đầu, hãy để accounts và proxies trống rồi thêm tài khoản thật sau thông qua Web UI.

{
  "listen": "127.0.0.1:8180",
  "auth_token": "CHANGE_ME_TO_A_LONG_RANDOM_TOKEN",
  "data_dir": "data",
  "agent_image": "agentbox-agent:latest",
  "accounts": [],
  "proxies": []
}

Thay thế giá trị giữ chỗ trước khi khởi động vì bước xác thực cấu hình sẽ từ chối giá trị này.

3. Khởi động máy chủ

sudo ./agentbox -config config.json

Đối với máy chủ chỉ lắng nghe trên localhost, hãy tạo SSH tunnel từ máy tính của bạn:

ssh -N -L 8180:127.0.0.1:8180 user@your-server

Mở http://127.0.0.1:8180 cục bộ và đăng nhập bằng boxadmin cùng auth_token đã cấu hình. Sau khi tài khoản quản trị được tạo, mật khẩu của tài khoản này sẽ được lưu trong SQLite; việc thay đổi auth_token sau đó không đặt lại mật khẩu.

4. Cài đặt dịch vụ systemd

Sau khi dừng tiến trình chạy ở chế độ nền trước, hãy cài đặt và triển khai dịch vụ từ kho mã:

sudo ./deploy/install.sh
sudo ./deploy/deploy.sh

Tập lệnh đầu tiên cài đặt dịch vụ và các bộ hẹn giờ. Tập lệnh thứ hai xây dựng và thay thế các tệp nhị phân, khởi động lại dịch vụ và thực hiện kiểm tra tình trạng.

Giám sát mức sử dụng và chi phí

Trang Usage ghi lại hoạt động của mô hình và cho phép quản trị viên lọc theo người dùng, mô hình và thời gian. Mỗi bản ghi bao gồm mức sử dụng token, nguồn chi phí và độ trễ. Người dùng thông thường chỉ có thể xem bản ghi của mình, còn quản trị viên có thể xem bản ghi của tất cả người dùng.

Danh mục giá có thể sử dụng preset nguồn models.dev hoặc các nguồn HTTPS tùy chỉnh. Các lần cập nhật giá vẫn giữ lại ảnh chụp lịch sử và giá tùy chỉnh vẫn được bảo vệ. Các lượt Web được tính giá theo bảng được ghim tại thời điểm lượt đó bắt đầu.

Giới hạn tín dụng không phải là mức trần cứng theo thời gian thực. Một lượt Web chỉ được quyết toán sau khi hoàn tất, vì vậy lượt làm cạn số dư có thể chi vượt mức. Mức sử dụng terminal được bổ sung sau vẫn được ghi nhận nhưng không trừ tín dụng.

Mẹo nâng cao

Sử dụng tài nguyên dùng chung giữa các workspace

Thư mục dùng chung của mỗi người dùng được gắn kết tại /shared trong tất cả workspace của người dùng đó. Hãy lưu các tập lệnh có thể tái sử dụng, tệp tham khảo hoặc hiện vật ở đó thay vì sao chép chúng vào từng dự án. Agentbox cũng hỗ trợ các template thư mục home cấp hệ thống và theo từng người dùng.

Truy cập dịch vụ riêng tư bằng abox-link

Ứng dụng khách abox-link tùy chọn cho phép workspace trên đám mây truy cập các dịch vụ được cho phép, khả dụng từ máy tính của bạn hoặc một máy riêng tư khác. Ứng dụng có thể chạy thông qua bảng điều khiển cục bộ hoặc ở chế độ máy chủ dòng lệnh với --server.

Hãy sử dụng danh sách cho phép giới hạn và chỉ cung cấp quyền truy cập đến các kho mã, cơ sở dữ liệu hoặc dịch vụ mà workspace cần. Agentbox hiển thị trạng thái sẵn sàng kết nối của cả máy khách và workspace. Việc sử dụng trình duyệt thông thường không yêu cầu abox-link.

Lập kế hoạch dung lượng container

Mỗi container workspace mặc định có 2048 MiB bộ nhớ, 2 CPU và 512 tiến trình. Hãy xác định cấu hình máy chủ dựa trên số lượng workspace dự kiến chạy đồng thời. Quản trị viên cũng có thể cấu hình giới hạn container toàn cục và theo từng người dùng, cùng dung lượng đĩa dự phòng.

Sao lưu đúng dữ liệu

Bản sao lưu hệ thống mặc định bao gồm cơ sở dữ liệu, cấu hình, thông tin xác thực tài khoản và các lớp template, nhưng không bao gồm dữ liệu workspace. Sử dụng agentbox backup --full khi cần sao lưu cả tệp người dùng và lịch sử. Bản sao lưu đầy đủ yêu cầu dừng dịch vụ và các container liên quan trước. Sử dụng backup-verify để xác thực kho lưu trữ và restore --to để khôi phục vào một thư mục mới.

Hiểu ranh giới bảo mật

Agent có thể thực thi mã bên trong các container workspace. Chế độ quyền mặc định là bypassPermissions. Container chạy dưới người dùng không có quyền root, với giới hạn tài nguyên và no-new-privileges, nhưng bản thân máy chủ Agentbox có quyền truy cập Docker. Do đó, việc triển khai và quản trị nên được giao cho các nhà vận hành đáng tin cậy.

Sử dụng trình duyệt từ xa tùy chọn một cách thận trọng

Agentbox có thể cung cấp một trình duyệt máy tính để bàn đầy đủ bên trong workspace, bao gồm trạng thái đăng nhập được lưu trữ, các tab, chế độ toàn màn hình, chất lượng hình ảnh có thể điều chỉnh, hỗ trợ clipboard và tải xuống. Quản trị viên phải xây dựng và chọn image tùy chọn agentbox-agent:browser. Việc xác thực website vẫn tách biệt với quyền ủy quyền của Claude hoặc Codex CLI.

Các giới hạn vận hành cần ghi nhớ

• Chỉ một tiến trình Agentbox có thể sử dụng một data_dir cụ thể.
• Kiến trúc production hiện tại sử dụng một máy, một tiến trình máy chủ và một Docker daemon cục bộ.
• Việc triển khai và khởi động lại sẽ làm gián đoạn kết nối của các máy khách trong thời gian ngắn.
• Việc làm mới trạng thái Git từ xa không thực hiện fetch; các giá trị ahead và behind lấy từ bộ nhớ đệm cục bộ.
• Thu hồi tài khoản không xóa thông tin xác thực đã được cung cấp cho container đang chạy.
• Dừng hoặc xây dựng lại container workspace sẽ chấm dứt các tiến trình của container, dù các tệp liên tục vẫn được giữ lại.
• Git review có thể khởi động một workspace đã dừng và áp dụng các kiểm tra cấp tín dụng giống như quyền truy cập terminal.

Kết luận

Agentbox biến máy chủ Linux thành môi trường lập trình bền vững trên trình duyệt cho Claude Code và Codex CLI. Hãy bắt đầu bằng trình cài đặt bản phát hành, thêm tài khoản, tạo workspace và chuyển từ một tác vụ trò chuyện sang mã đã được xem xét thông qua các chế độ xem Files, Terminal và Changes tích hợp. Để sử dụng trong production, hãy bổ sung HTTPS, kiểm soát cẩn thận quyền truy cập tài khoản, giám sát mức sử dụng tài nguyên và thiết lập kế hoạch sao lưu bao gồm dữ liệu workspace khi cần.

Để biết thêm hướng dẫn cấu hình và vận hành, hãy tham khảo kho mã Agentbox, mục lục tài liệu và hướng dẫn triển khai và vận hành.