SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor

Tự host OneCLI: mỗi người một agent riêng

Tự host OneCLI trên VPS với Docker Compose và PostgreSQL: mỗi người có sandbox riêng, API key nằm ở gateway; mặc định cần 2 GiB memory cho mỗi agent.

Bạn nhận được gì khi tự host OneCLI

Tự host OneCLI giúp mỗi người trong team có một agent riêng. Mỗi agent chạy trong sandbox riêng. API key được giữ trong một gateway mà các agent không bao giờ đọc được. Bộ cài là một stack Docker Compose có PostgreSQL phía sau, có thể truy cập tại http://localhost:10254. Hãy chuẩn bị một máy chủ thực tế. Mặc định được tài liệu ghi nhận là giới hạn 2 GiB bộ nhớ cho mỗi sandbox của agent. Vì vậy, hãy tính riêng tài nguyên cho stack cơ sở và bộ nhớ thực tế mà các agent sử dụng.

Stack này có tám thành phần. Biết chức năng của từng thành phần sẽ giúp bạn đọc phần còn lại của hướng dẫn dễ hơn.

  • Web dashboard (Next.js), cổng 10254. Tạo agent, chat, chỉnh sửa memory và skills, quản lý connections và secrets.
  • API server, cổng 10256. Control plane: database, xử lý hội thoại và work queue.
  • Rust gateway, cổng 10255. Chặn các request outbound từ agent và chèn thông tin xác thực.
  • Runner. README mô tả đây là thành phần “khởi động, tạm dừng và thu hồi sandbox của agent. Chỉ outbound và không bao giờ truy cập database.”
  • Sandbox Supervisor. README mô tả thành phần này chạy “bên trong từng sandbox, giao tiếp qua một harness interface không phụ thuộc vendor để có thể thay thế agent runtime.”
  • SSH terminator, cổng 10257. README gọi đây là “cổng SSH phía trước”: thành phần này terminate SSH bằng các certificate ngắn hạn do API cấp, rồi chuyển tiếp từng session vào sandbox của agent. Nó chạy dưới cùng profile runner với runner.
  • Channel adapter. Một daemon kết nối với Slack app để agent trả lời trong channel và DM bằng tên riêng của agent.
  • PostgreSQL. File compose đi kèm chạy postgres:18-alpine với một volume pgdata.

Tên gọi là CLI, nhưng sản phẩm là một server

OneCLI là một nền tảng server. Tên gọi khiến bạn nghĩ đây là một command line tool được cài trên laptop, nhưng đó không phải mô hình của sản phẩm trong hướng dẫn này. Có một command line client riêng trong repository onecli/onecli-cli. Client này định tuyến traffic của coding agent cục bộ qua một gateway. Thành phần bạn triển khai ở đây là một web application nhiều người dùng: hệ thống tài khoản có organization và lời mời, database lưu các cuộc hội thoại và secret, cùng một runner khởi động các container.

Mô hình mỗi người một agent là nền tảng của toàn bộ thiết kế. README viết: “Bạn tạo một agent cho mỗi người, cấp cho từng agent quyền truy cập cần thiết, rồi agent chạy trong sandbox và được định tuyến qua một gateway. Gateway này inject credential và áp dụng policy của bạn.” Mỗi agent có filesystem và shell riêng, trang hội thoại riêng, memory do platform lưu giữ, cùng các skill bạn chỉ cần viết một lần. Cách xử lý credential cũng ngược với mô hình thông thường. Thay vì chép API key vào environment của từng người, bạn lưu key một lần rồi cấp quyền sử dụng key đó cho các agent được phép.

Những gì máy chủ cần có trước khi bắt đầu

  • Docker, với Compose plugin phiên bản 2.24.0 trở lên. File compose đi kèm sử dụng các mapping env_file tùy chọn cùng với required: false, được Docker hỗ trợ từ phiên bản 2.24.0. Các comment migration giải thích mốc tối thiểu 2.19 là để hỗ trợ dependency chạy một lần trong up --wait, nhưng mức này không hỗ trợ các file môi trường tùy chọn của file.
  • Bộ nhớ là giới hạn thực tế. Đọc phần sizing bên dưới trước khi chọn plan.
  • Các cổng loopback 10254, 10255, 10256, 10257 và 5432 còn trống. Cổng 10257 là cổng SSH chính, được khởi động cùng profile runner mà hướng dẫn này bật.

Bạn không cần tự cài PostgreSQL: file compose chạy PostgreSQL dưới dạng một service. Wizard thiết lập bên dưới cần Node.js và pnpm trên host. Khi làm việc trực tiếp với code, bạn cũng dùng mise để cố định toolchain, bao gồm Rust cho gateway.

Bao nhiêu agent sandbox có thể chạy trên VPS của bạn?

Tài liệu của runner đưa ra các con số cụ thể. Mỗi sandbox bị giới hạn ở 2048 MB bộ nhớ (RUNNER_SANDBOX_MEMORY_MB), một CPU (RUNNER_SANDBOX_CPUS) và 512 process (RUNNER_SANDBOX_PIDS). Giới hạn concurrency là 4 (RUNNER_MAX_SANDBOXES). Tài liệu khuyến nghị có khoảng 10 GiB bộ nhớ trống ngoài stack cơ bản để đáp ứng giới hạn này.

Biểu đồAgent memory budgets per box, using the documented 2 GiB cap
Dữ liệu đằng sau biểu đồ này
[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

Các con số slot này chỉ là phép tính, không phải benchmark: lấy tổng bộ nhớ, trừ khoảng 2 GB giả định dành cho PostgreSQL và các service chạy lâu khác, rồi chia cho giới hạn 2 GiB của mỗi sandbox. Theo cách tính đó, 2 GB box có ngân sách cho 0 sandbox ở mức giới hạn bộ nhớ tối đa; giá trị zero nghĩa là không có ngân sách cho sandbox ở mức tối đa theo các giả định này, không có nghĩa là Docker từ chối khởi động agent. 16 GB box còn đủ chỗ cho 7, cao hơn đáng kể giới hạn mặc định là 4 và cao hơn mức khoảng 10 GiB bộ nhớ trống mà tài liệu của runner yêu cầu. 32 GB box cho phép chạy 15. Muốn chạy đồng thời nhiều hơn 4 sandbox, bạn cũng phải tăng RUNNER_MAX_SANDBOXES.

Có hai yếu tố làm thay đổi phép tính này. Sandbox có process chạy nền sẽ không được đưa về trạng thái chờ, nên giữ slot vĩnh viễn. Vì vậy, bạn phải tính RUNNER_MAX_SANDBOXES theo tải duy trì, không phải theo phút có tải cao nhất. Platform có giới hạn cho trường hợp này: theo mặc định, mỗi runner chỉ giữ tối đa RUNNER_MAX_SANDBOXES trừ một sandbox đang hoạt động (không bao giờ ít hơn một sandbox; có thể ghi đè bằng MAX_HELD_AWAKE_SANDBOXES trên API). Khi vượt quá giới hạn đó, runner sẽ loại sandbox ít hoạt động lâu nhất và báo process đang được theo dõi của sandbox đó là đã mất. Mức sử dụng bộ nhớ và CPU phụ thuộc vào workload. Mỗi sandbox bị giới hạn ở một CPU, nên 4 agent bận có thể dùng 4 core. Tuy nhiên, thiết lập bộ nhớ 2 GiB là giới hạn tối đa, không phải lượng bộ nhớ được reserve: 4 agent đang chờ nhưng vẫn hoạt động không tự động dùng 8 GiB.

Các thiết lập Runner bạn có thể muốn thay đổi
  • RUNNER_MAX_SANDBOXES (mặc định 4): số sandbox chạy đồng thời.
  • RUNNER_SANDBOX_MEMORY_MB (mặc định 2048): giới hạn bộ nhớ cho mỗi sandbox.
  • RUNNER_SANDBOX_CPUS (mặc định 1): giới hạn CPU cho mỗi sandbox.
  • RUNNER_SANDBOX_PIDS (mặc định 512): giới hạn process cho mỗi sandbox.
  • RUNNER_NETWORK_INTERNAL (mặc định true): giữ network của sandbox không có route đi ra ngoài. Hãy để bật.
  • RUNNER_SANDBOX_NETWORK (mặc định onecli-sandboxes): network mà các sandbox tham gia.
  • RUNNER_RECONCILE_SECONDS (mặc định 60): khoảng thời gian runner reconcile state một lần.
  • RUNNER_ORPHAN_GRACE_SECONDS (mặc định 3600): thời gian tồn tại trước khi các container và volume mồ côi bị xóa.
  • RUNNER_AGENT_IMAGE: ghi đè sandbox image; nếu không, image này sẽ theo ONECLI_VERSION.

Cài đặt OneCLI bằng Docker Compose

Tài liệu tự host của upstream ghi một chuỗi lệnh thô để viết 3 secret vào docker/.env bên cạnh file compose. Chuỗi lệnh đó bỏ qua runner token, Docker socket group và thông tin xác thực SSH mà các service được bật cần dùng, vì vậy hãy chạy setup wizard trước khi khởi động stack.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

Đọc block đó trước khi chạy. Heredoc marker không được đặt trong dấu nháy, nên shell sẽ chạy từng head -c 32 /dev/urandom | base64 và ghi kết quả thay vì ghi nguyên văn nội dung. SECRET_ENCRYPTION_KEY là khóa AES-256-GCM dùng cho mọi secret trong database. GATEWAY_INTERNAL_SECRET xác thực gateway với API. BETTER_AUTH_SECRET dùng để ký session cookie. COMPOSE_PROFILES=runner là dòng quan trọng nhất, vì runner service nằm sau một Compose profile: bỏ qua dòng này thì stack vẫn khởi động ở trạng thái healthy nhưng không có agent sandbox nào được chạy.

--wait chờ các service ở trạng thái running hoặc healthy và dependency migrations hoàn tất thành công, nên exit code khác 0 là tín hiệu đầu tiên cho thấy có vấn đề. Sau đó kiểm tra chính xác những gì đã khởi động.

docker compose ps
docker compose logs migrations

Cố định version. ONECLI_VERSION đặt tag cho tất cả service cùng lúc, và image của agent sandbox cũng dùng tag đó trừ khi RUNNER_AGENT_IMAGE trỏ đến nơi khác. Dùng số version thuần: các image tag đã publish không có tiền tố v. Tính đến ngày 1 tháng 11 năm 2026, bản release hiện tại là v2.17.0, được publish ngày 31 tháng 10 năm 2026. Thêm version này vào cùng file, sau đó dùng quy trình upgrade được tài liệu hướng dẫn để các sandbox đang chạy cũng chuyển sang image đó.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

Ngoài ra còn có installer là curl -fsSL https://onecli.sh/install | sh, installer này ghi cấu hình vào ~/.onecli/.env và thực hiện cùng công việc. Nó đặt ONECLI_VERSION=latest cho lần chạy của chính nó, ghi đè pin chỉ được giữ trong file .env đó. Quy trình Compose cho phép bạn đọc mọi file trước khi bất kỳ thứ gì chạy, và nên dùng quy trình này trên máy đã chạy các Compose stack khác. Thiết lập checkout ở trên upgrade bằng pnpm run setup --upgrade. Quy trình đó yêu cầu Node.js và pnpm trên host; nếu trực tiếp làm việc trên code thì cần thêm mise và Rust cho gateway, nên phù hợp với người dự định thay đổi OneCLI. Với Kubernetes, release v2.11.0 (8 tháng 10 năm 2026) đã thêm Helm chart; chart hiện tại chạy agent sandbox dưới dạng Job với persistent volume, không cần Docker daemon, đồng thời có tài liệu về các secret, database và cấu hình routing bắt buộc.

Truy cập dashboard từ laptop

Mọi port được publish trong file compose đi kèm đều bind vào ${ONECLI_BIND_HOST:-127.0.0.1}. Trên VPS, điều đó có nghĩa là dashboard đang chạy nhưng không thể được truy cập từ bên ngoài máy chủ. Đây là thiết lập mặc định đúng. Hãy giữ nguyên và tạo tunnel:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

Bây giờ mở http://localhost:10254 trên laptop. Traffic đi qua kết nối SSH, nên không có dashboard không mã hóa nào được public trên Internet và bạn cũng không cần mở thêm port trên firewall.

Thiết lập ONECLI_BIND_HOST=0.0.0.0 sẽ publish dashboard qua HTTP thuần, đồng thời publish PostgreSQL với password mặc định của file compose là onecli, trừ khi bạn đặt POSTGRES_PASSWORD. Thiết lập này cũng publish SSH front door trên port 10257, một service mount Docker socket. Nếu có nhiều người cần dashboard, hãy đặt reverse proxy có TLS (transport layer security) ở phía trước và giữ nguyên bind host. Đặt ONECLI_EXTERNAL_URL thành URL HTTPS của proxy và dùng cấu hình reverse proxy của upstream. Cấu hình này định tuyến các path của dashboard, API và gateway đến đúng service tương ứng. Chỉ có proxy thì không ngăn được người lạ truy cập. Tài liệu self-hosting nêu rõ registration được mở theo thiết kế và không có tùy chọn để tắt: bất kỳ ai truy cập được dashboard đều có thể tạo account riêng, account đó có organization riêng; chỉ việc tham gia organization của bạn mới cần invitation. Tài liệu khuyến nghị giữ dashboard phía sau ranh giới mạng của bạn. Nếu proxy đó đã đứng trước các app self-hosted khác, forward auth qua một lớp single sign-on self-hosted sẽ đặt dashboard phía sau login mà team của bạn đang dùng. Khi xóa một người ở đó, bạn cũng đồng thời đóng quyền truy cập vào dashboard này.

Tạo tài khoản đầu tiên, rồi cấp model key

Mở dashboard và tạo tài khoản ngay. Mỗi tài khoản mới có một organization riêng, còn đồng đội tham gia organization của bạn qua lời mời. Sau đó tính năng đăng ký vẫn được mở. Đây là thêm một lý do để đặt dashboard phía sau tunnel hoặc proxy có xác thực. Nếu bạn nâng cấp từ một release chưa có chức năng đăng nhập, hãy đăng ký ngay: tài liệu self-hosting nói rằng dữ liệu hiện có sẽ được gán cho tài khoản đầu tiên đăng ký. Vì vậy, trên một host có thể truy cập được, bạn cần bảo đảm tài khoản đó là của mình.

Sau đó lưu model key trước khi tạo agent. Hosted agent cần một model key đã được cấp quyền, và thứ tự này rất quan trọng: lưu key trong dashboard, cấp key cho agent, rồi mới bắt đầu conversation. Nếu bỏ qua bước cấp quyền, sandbox sẽ không khởi chạy; agent sẽ trả lời trong thread rằng nó cần một model key.

Chỉ cấp quyền ở phạm vi cần thiết. Mỗi agent chỉ nhận được những quyền bạn đã cấp, và gateway kiểm tra điều đó trong mọi request. Vì vậy, agent chỉ đọc một repository sẽ không có đường truy cập đến key của payment provider. Danh sách quyền cấp cũng là công cụ kiểm soát chi phí. Một agent riêng cho từng người có thể gọi mọi model bạn sở hữu sẽ tạo ra invoice riêng cho từng người. Vì vậy, hãy đọc cách giới hạn số tiền agent có thể chi cho các lần gọi model trước khi cấp quyền cho mười agent.

Cách gateway giữ key ngoài các agent

Gateway là một HTTPS proxy viết bằng Rust, lắng nghe trên port 10255. HTTP client của agent được trỏ đến gateway, còn agent mang một credential placeholder thay vì credential thật. Gateway đối chiếu request gửi đi với các grant của agent đó, giải mã secret thật, thay secret vào request rồi chuyển tiếp request. Các secret được lưu trong PostgreSQL dưới dạng mã hóa bằng AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode) và chỉ được giải mã tại thời điểm xử lý request. Mọi lần gọi đều được log cùng identity của agent và đích đến. Đây là audit trail mà bạn không thể có khi key nằm trong shell profile của mười người.

Hai cơ chế quyết định cách bạn triển khai gateway.

  • HTTPS interception là một cuộc tấn công man-in-the-middle. Gateway tạo một certificate authority cục bộ, agent trust certificate authority này, rồi gateway terminate kết nối TLS của agent và mở một kết nối mới đến upstream service. Vì vậy, agent có HTTP client không trust certificate authority của gateway sẽ fail với lỗi certificate verification thay vì lỗi authentication.
  • Agent tự xác định bằng header Proxy-Authorization. Trên một máy duy nhất, nơi agent và gateway dùng chung một Docker network nội bộ, header này không bao giờ đi qua network mà bạn không kiểm soát. Nếu trỏ agent ở máy khác đến gateway, hãy bảo vệ kết nối bằng VPN hoặc TLS transport, vì header này là bearer token; upstream khuyến nghị dùng VPN cho raw CONNECT proxy port.

Đánh đổi cần nói rõ: gateway đọc plaintext của mọi request mà agent gửi, theo đúng thiết kế. Đây là process nhạy cảm nhất trên máy. Hãy bảo vệ host tương ứng và giới hạn số người có quyền đăng nhập bằng Linux user theo nguyên tắc đặc quyền tối thiểu.

Vì sao runner không cần cổng inbound

Runner chỉ tạo kết nối outbound. Tài liệu của runner viết: “nó không mở cổng nào mà Internet có thể truy cập, nên laptop, homelab hoặc VPC nằm sau NAT đều hoạt động mà không cần ingress, tunnel hay xử lý TLS termination.” NAT là network address translation, cơ chế mà router gia đình sử dụng. Runner tự kết nối đến control plane rồi lấy công việc từ đó, nên không có gì cần forward và cũng không có cổng nào cần mở.

Thiết kế này phát huy tác dụng trong sandbox network. File compose định nghĩa một network thứ hai có đánh dấu internal: true; trong Docker, điều này có nghĩa là network không có kết nối mạng bên ngoài. Các sandbox tham gia network này. Gateway có kết nối đến cả hai network, nên đây là đường duy nhất để đi ra ngoài. Tài liệu của runner nêu rõ: “một network internal với gateway có kết nối đến cả hai network là yếu tố biến việc chỉ cho phép egress qua gateway thành một ranh giới thực tế thay vì chỉ là khuyến nghị.” Agent không thể bypass gateway bằng cách mở kết nối trực tiếp đến một địa chỉ bên ngoài; policy của gateway vẫn quyết định request nào được phép.

Hãy tự xác nhận trên máy của bạn thay vì chỉ tin đoạn trên.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

Bạn sẽ thấy "Internal": true. Nếu kết quả là false, kiểm soát egress đang tắt và gateway lại chỉ là một khuyến nghị. Hãy dùng tên sandbox network mà docker network ls in ra, vì onecli-sandboxes chỉ là giá trị mặc định.

Mức độ mạnh của sandbox OneCLI đến đâu?

Đọc chậm phần này, vì từ “sandbox” có vai trò rất lớn trong phần mô tả của chính dự án, trong khi cơ chế này được ghi trong tài liệu về runner và mã backend.

README nói mỗi agent có “sandbox cô lập riêng, với filesystem và shell riêng”, đồng thời gọi Sandbox Supervisor là thành phần “chạy bên trong từng sandbox, giao tiếp qua một harness interface không phụ thuộc vendor để có thể thay thế agent runtime”. Cả hai câu này đều không nói isolation được tạo bằng gì. Tài liệu của runner có nói rõ: backend mặc định là Docker (RUNNER_BACKEND=docker), còn sandbox là một Docker container có giới hạn memory, CPU và số lượng process, được gắn vào internal network. Code có sẵn một lớp để hỗ trợ các backend khác. Mã runner hiện tại cũng triển khai backend Kubernetes, được Helm chart dùng cho các sandbox Job và persistent volume. Trong mô hình cài đặt Compose của hướng dẫn này, sandbox là một Docker container.

Tài liệu runner hiện mô tả boundary của Docker: agent chạy dưới dạng node, với no-new-privileges, toàn bộ Linux capability bị loại bỏ và dùng seccomp profile mặc định của Docker. Backend chỉ mount home bền vững của agent vào sandbox. Vì vậy, hãy hiểu theo nghĩa hẹp. Các giới hạn này là giới hạn tài nguyên. Internal network là một cơ chế kiểm soát egress thực sự. Isolation giữa agent và host của bạn dựa trên các cơ chế kiểm soát container này, còn container vẫn dùng chung kernel của host.

Có một yếu tố khác cần cân nhắc. Runner service mount /var/run/docker.sock vì đó là cách nó tạo sandbox. Quyền truy cập vào socket của Docker daemon chạy với root tương đương với quyền root trên host, vì bất kỳ ai gọi được API đó đều có thể khởi động một container và mount filesystem của host vào bên trong container. Runner dùng Docker đi kèm dự án sử dụng socket này. Hệ quả là runner process nhạy cảm không kém gateway. SSH terminator cũng mount cùng socket để có thể exec vào các sandbox container, và comment trong compose file cũng gọi mount này là tương đương quyền root trên host. Vì vậy, hãy giữ port 10257 chỉ bind trên loopback, trừ khi bạn có lý do cần mở port này.

Hãy đánh giá boundary dùng chung kernel một cách thận trọng. Trong thực tế, điều đó có nghĩa là duy trì 3 thói quen sau.

  1. Chạy OneCLI trên một máy không làm việc gì khác. Không chạy service production không liên quan, không dùng chung database và không chứa dữ liệu của team khác.
  2. Giả định rằng agent có quyền thực thi code tùy ý bên trong sandbox có thể tiếp cận host, đồng thời chuẩn bị backup lưu ngoài máy để sự cố đó vẫn có thể xử lý được.
  3. Đọc apps/runner/src hoặc hỏi upstream trước khi nói với đồng nghiệp rằng agent đã được containment.

Để xem một boundary được tài liệu hóa thường trông như thế nào và biết nên hỏi upstream những gì, hãy so sánh nội dung này với boundary sandbox thực tế của agent trông như thế nào. Câu hỏi cốt lõi là cơ chế được tài liệu hóa có bao phủ các mối đe dọa mà bạn cần ngăn chặn hay không.

Phân tách giấy phép và lý do cần kiểm tra trước khi triển khai

Phần core của OneCLI dùng Apache-2.0 và được phép self-host trong môi trường production. Các thư mục có tên ee/ thuộc OneCLI Enterprise License riêng: miễn phí cho development, testing và evaluation, nhưng cần subscription để sử dụng trong production. Release notes của v2.0.1 ngày 18 August 2026 đề cập việc khôi phục file licence Apache-2.0 để GitHub có thể phát hiện, nên badge trên trang repository gần đây đã thay đổi. Hãy kiểm tra tag mà bạn thực sự triển khai, thay vì dựa vào một bản tóm tắt được viết vào thời điểm khác.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

Mọi thứ nằm trong các path đó đều thuộc phần thương mại. Nếu feature mà bạn dự định phụ thuộc vào nằm ở đó, hãy kiểm tra chi phí trước khi xây dựng quy trình dựa trên feature đó.

Nâng cấp, migration và file duy nhất bạn không được làm mất

Nâng cấp phải cập nhật các service image và agent image riêng, sau đó restart các sandbox đang chạy. Một migrations service chạy một lần sẽ chạy trước API ở mỗi up. Nếu migration thất bại, stack sẽ từ chối khởi động thay vì phục vụ với schema mới chỉ được cập nhật một phần. Đây là hành vi bạn cần, vì khi nâng cấp thất bại, vấn đề sẽ biểu hiện như một outage thay vì âm thầm làm hỏng dữ liệu. docker compose logs migrations giải thích lý do.

Có một bước rất dễ bị bỏ sót. Tài liệu self-hosting cảnh báo không nâng cấp bằng docker compose pull && docker compose up -d đơn thuần, vì agent sandbox image không phải là một Compose service. Nó là giá trị RUNNER_AGENT_IMAGE trên runner, nên docker compose pull không bao giờ nhìn thấy nó. Vì vậy, hosted agent có thể tiếp tục dùng sandbox image cũ mà không có cảnh báo. Hãy cập nhật checkout, thay đổi pin và chạy công cụ nâng cấp được tài liệu hướng dẫn. Công cụ này sẽ pull sandbox image và restart các sandbox đang chạy.

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

Thay 2.17.0 bằng bản release bạn muốn nâng cấp lên. Việc restart sandbox sẽ làm gián đoạn công việc đang chạy; workspace bền vững của từng agent vẫn được giữ nguyên.

Nếu bạn cài đặt bằng install script, hãy chạy lại script đó thay vì tự pull image. Cách này giữ cho compose file đồng bộ với các image mà file tham chiếu. Trước tiên hãy export ONECLI_VERSION nếu bạn muốn dùng một release cụ thể, vì script sẽ ghi đè pin chỉ được lưu trong file .env của nó.

Hãy backup database, cấu hình và các agent workspace volume. PostgreSQL lưu agents, conversations, memory và các secret đã mã hóa. File docker/.env lưu SECRET_ENCRYPTION_KEY. Không có key này, các secret đã mã hóa sẽ không thể đọc được, ngay cả khi phần còn lại của database đã được restore. /workspace của mỗi agent nằm trên một durable volume riêng và cần được backup riêng.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Hãy lưu các bản sao đó và các bản backup workspace bên ngoài máy chủ. Quy trình này giống với quy trình cần dùng cho mọi stateful Compose stack. Vì vậy, nếu bạn đã backup và nâng cấp một Docker Compose stack theo lịch, hãy thêm các database, cấu hình và workspace volume vào quy trình đó rồi không cần bận tâm thêm.

Khi hệ thống không hoạt động

  • Stack không bao giờ chuyển sang trạng thái healthy và docker compose up -d --wait thoát với mã khác 0. Đọc docker compose logs migrations trước, vì API cố ý chờ service đó.
  • Agent không hoạt động và không có sandbox nào xuất hiện. Kiểm tra COMPOSE_PROFILES=runner có trong docker/.env hay không và docker compose ps có liệt kê runner hay không. Sau đó kiểm tra agent đã được cấp model key chưa, vì sandbox sẽ không khởi chạy nếu thiếu key này.
  • Không còn slot. RUNNER_MAX_SANDBOXES mặc định là 4. Sandbox có process chạy nền sẽ giữ slot cho đến khi cơ chế giới hạn thời gian giữ thức loại bỏ sandbox đó. docker ps cho biết những gì thực sự đang chạy.
  • Stack không khởi động được và Docker báo cổng đã được sử dụng. Khi bật profile runner, SSH front door cần cả 10257 ngoài 4 cổng còn lại.
  • Container biến mất hoặc host chạy rất chậm. Kiểm tra tình trạng cạn bộ nhớ bằng dmesg -T | grep -i oom; giới hạn bộ nhớ mặc định cho phép một sandbox sử dụng tối đa 2048 MB.
  • Các lệnh gọi HTTPS của agent thất bại với lỗi xác minh certificate thay vì lỗi authentication. HTTP client của agent không tin cậy certificate authority của gateway.
  • Container hoặc volume cũ vẫn còn sau khi bạn xóa agent. Runner reconcile mỗi 60 giây và xóa orphan cũ hơn RUNNER_ORPHAN_GRACE_SECONDS, mặc định là 3600, vì vậy hãy chờ một giờ trước khi kết luận đây là memory leak.

Đây có phải là lựa chọn phù hợp với bạn không?

Bài kiểm tra mức độ phù hợp khá ngắn. OneCLI phù hợp khi nhiều người đều cần một agent và bạn muốn quản lý credentials ở một nơi: một store để xoay vòng, một audit log để đọc, một dashboard để khi thu hồi quyền truy cập của một người thì quyền đó thực sự bị thu hồi. Đây là một vấn đề vận hành thực tế, và việc sao chép một API key vào 6 laptop là cách xử lý tệ hơn.

Với một người dùng, đây là quá nhiều thành phần mà không đem lại lợi ích tương xứng. Bạn sẽ phải chạy PostgreSQL, một control plane, một gateway và một runner chỉ để cung cấp cho mình một agent. Vấn đề credential mà gateway giải quyết hầu như không tồn tại khi người duy nhất giữ key là bạn. Thay vào đó, hãy chạy một harness duy nhất trên một máy nhỏ hơn: một harness agent duy nhất trên VPS có thể làm việc đó với lượng memory chỉ bằng một phần. Nếu bạn vẫn chưa chọn hướng nào, bài tổng quan so sánh các self-hosted AI agent là bước đầu rẻ hơn. Nếu phần xa lạ là bản thân agent chứ không phải các server chạy chúng, trước tiên hãy làm theo lộ trình từng giai đoạn để tìm hiểu agent thực sự hoạt động như thế nào. Hiểu rõ tool call và memory store thực sự làm gì sẽ giúp bạn xác định agent của mỗi người nên được cấp những quyền nào.

FAQ

Yêu cầu tối thiểu của máy chủ để tự host OneCLI là gì?

Bạn cần Docker có Compose plugin phiên bản 2.24.0 trở lên, Node.js và pnpm cho setup wizard được dùng trong hướng dẫn này, cùng đủ bộ nhớ. PostgreSQL đã có trong compose file nên bạn không cần cài riêng. Bộ nhớ quyết định cách lập kế hoạch: runner giới hạn mỗi agent sandbox ở mức 2048 MB theo mặc định, và tài liệu yêu cầu khoảng 10 GiB bộ nhớ trống ngoài base stack để phục vụ giới hạn mặc định là bốn sandbox. Theo ngân sách 2 GB cho base stack được giả định trong biểu đồ, máy 4 GB có thể dành một sandbox ở mức giới hạn tối đa, còn máy 16 GB đáp ứng giới hạn concurrency mặc định. Đây là các con số để lập kế hoạch, không phải yêu cầu tối thiểu đã được đo hoặc mức cấp phát bộ nhớ cố định.

OneCLI có cần PostgreSQL không, hay có thể dùng SQLite?

OneCLI cần PostgreSQL. DATABASE_URL được mô tả là PostgreSQL connection string, compose file đi kèm chạy postgres:18-alpine với một volume pgdata, và một migrations service riêng áp dụng schema trước khi API khởi động. Không có tùy chọn SQLite nào được mô tả. Nếu dùng PostgreSQL server bên ngoài, hãy cấu hình cả API và migrations service sử dụng server đó; compose file đi kèm đặt connection string của hai service này trỏ đến PostgreSQL service đi kèm.

Agent sandbox của OneCLI có phải là một security boundary thực sự không?

Cơ chế Compose được tài liệu hóa là một Docker container có giới hạn memory, CPU và process, được kết nối với network đánh dấu internal: true để traffic ra ngoài đi qua gateway. Egress control là cơ chế thực và bạn có thể xác minh bằng docker network inspect. Agent chạy dưới tài khoản node, với no-new-privileges, toàn bộ Linux capabilities bị loại bỏ và dùng Docker default seccomp profile, nhưng vẫn chia sẻ kernel của host. Runner và SSH terminator đều mount /var/run/docker.sock, tương đương quyền root trên host sử dụng rootful Docker daemon. Hãy chạy OneCLI trên một máy riêng và lưu backup bên ngoài máy đó.

Tôi có cần mở cổng inbound nào cho OneCLI không?

Không. Runner chỉ tạo kết nối outbound và không giữ cổng nào mà thế giới bên ngoài có thể truy cập, nên có thể hoạt động phía sau NAT mà không cần tunnel. Compose file bind dashboard, gateway, API, PostgreSQL và, khi dùng profile runner, SSH front door trên cổng 10257 vào 127.0.0.1 theo mặc định. Truy cập dashboard qua SSH tunnel, hoặc dùng cấu hình reverse proxy của upstream với TLS và các route dashboard, API, gateway bắt buộc nếu có nhiều người cần sử dụng. Lưu ý rằng registration vẫn mở cho bất kỳ ai có thể truy cập nó. Gateway trên cổng 10255 dành cho agent; trên một máy đơn, các agent này truy cập gateway qua internal Docker network.

OneCLI có miễn phí để sử dụng trong công ty không?

Phần core dùng Apache-2.0 và được phép sử dụng trong production theo mô hình self-hosted mà không cần commercial licence. Các thư mục có tên ee/ thuộc OneCLI Enterprise License. License này miễn phí cho development, testing và evaluation, nhưng cần subscription khi dùng trong production. Phạm vi phân chia thay đổi giữa các release. Ghi chú của v2.0.1 ngày 18 August 2026 cho biết đã khôi phục file licence Apache-2.0 có thể được GitHub nhận diện. Vì vậy, hãy kiểm tra LICENSE và các thư mục ee/ trong đúng tag bạn triển khai trước khi xây dựng workflow dựa trên bất kỳ feature riêng lẻ nào.

Bài viết này có hữu ích không?