Bởi Matt Connor 2026-08-16 · Cập nhật ngày 2026-08-28

Hướng dẫn tự host SandBase agent runtime trên VPS

Q: Có an toàn không khi mở runtime trên một cổng công khai?

Không, nếu để nguyên cấu hình mặc định. Nó bind vào 127.0.0.1:3000 và khởi chạy mà không bật xác thực, và giải pháp không phải là thay đổi địa chỉ bind. Hãy tạo một API key, hoặc thiết lập MANAGED_AGENTS_API_KEY để bật xác thực bằng bearer-token. Sau đó, đặt nginx hoặc Caddy phía trước để xử lý TLS, và đóng cổng 3000 trên firewall để đường truy cập duy nhất là thông qua proxy.

Q: Sự khác biệt giữa sandbox cục bộ, Docker và Kubernetes là gì?

local chạy code công cụ như một tiến trình con của runtime trên host, với quyền của người dùng chạy runtime và không có sự cô lập. docker cấp cho mỗi phiên làm việc một container riêng với hệ thống file, giới hạn bộ nhớ và CPU share riêng, và xóa nó khi phiên làm việc kết thúc. kubernetes chạy phiên làm việc dưới dạng một pod và điều khiển nó bằng kubectl exec, yêu cầu kubectl bên trong image của runtime và RBAC trên các pod cộng với subresource exec trong namespace đích.

Q: Chính xác thì tôi cần sao lưu những gì?

Thư mục .managed-agents/ trong workspace. Nó chứa config.yaml, cơ sở dữ liệu SQLite data.db với các agent, phiên làm việc, mục nhập trong kho lưu trữ credential và bộ nhớ, cùng với các file đã tải lên, gói kỹ năng và snapshot của phiên làm việc. Hãy dừng dịch vụ trước khi sao chép để SQLite không bị ghi dữ liệu trong quá trình lưu trữ. Các API key của nhà cung cấp được tham chiếu dưới dạng ${OPENAI_API_KEY} không nằm trong bản sao lưu, vì vậy hãy lưu trữ chúng riêng biệt.

Hướng dẫn cài đặt SandBase Harness v0.3.2 trên VPS Ubuntu. Cấu hình agent YAML, thiết lập MCP servers, chế độ sandbox và trỏ Anthropic SDK về máy chủ của bạn để bảo mật dữ liệu.

Những gì bạn nhận được khi tự host SandBase agent runtime

Tự host SandBase agent runtime nghĩa là bạn chạy SandBase Harness trên máy chủ của chính mình. Nhờ đó, các phiên làm việc, thông tin xác thực, bộ nhớ và nhật ký kiểm toán sẽ nằm trên ổ cứng của bạn thay vì của bên thứ ba. Đây là một Node service. Nó lắng nghe trên 127.0.0.1:3000, cung cấp /v1 HTTP API cùng một web console, đồng thời lưu trữ trạng thái trong SQLite ngay cạnh các file agent của bạn.

/v1 API được thiết kế dựa trên Claude Managed Agents (CMA), một API quản lý agent được host sẵn. Đây là điểm khiến runtime này trở nên thú vị theo cả hai chiều: bạn có thể viết code dựa trên Anthropic SDK, trỏ baseURL của nó về máy chủ của bạn, sau đó chuyển cùng đoạn code đó sang một môi trường triển khai được host sẵn sau này.

SandBase Harness không đi kèm model. Nó gọi đến model. Tính đến tháng 8 năm 2026, nó hỗ trợ OpenAI, Anthropic và các endpoint tương thích với OpenAI, bao gồm cả các gateway tự host và các nhà cung cấp như DeepSeek V4. Bạn vẫn cần cung cấp API key hoặc một máy chủ cục bộ có hỗ trợ OpenAI API.

Những thứ bạn cần trước khi bắt đầu

Một VPS chạy Ubuntu 24.04 với tối thiểu 2 GB RAM. Quá trình build TypeScript là bước tốn tài nguyên nhất khi cài đặt.
Node.js 22 trở lên và npm 10 trở lên. Đây là yêu cầu tối thiểu bắt buộc từ dự án.
git, cùng với một API key cho nhà cung cấp model mà bạn dự định sử dụng.
Docker, chỉ cần thiết nếu bạn muốn sử dụng container sandbox cho từng phiên làm việc.

Ubuntu 24.04 cung cấp sẵn Node 18.19 trong repository của nó, phiên bản này thấp hơn mức tối thiểu, vì vậy hãy cài đặt Node từ NodeSource.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -v

node -v cần hiển thị v22 hoặc cao hơn và npm -v cần hiển thị 10 hoặc cao hơn. Nếu node -v vẫn hiển thị v18.19.1, nghĩa là gói cài đặt của hệ điều hành vẫn đang tồn tại và được ưu tiên trong PATH. Hãy gỡ bỏ nó trước khi tiếp tục, vì quá trình build sẽ sử dụng bất kỳ node nào mà shell tìm thấy trước.

Cài đặt SandBase từ tag v0.3.2

Hãy cài đặt từ một tag, đừng bao giờ dùng một branch đang thay đổi. Một bản clone thuần túy của main sẽ cung cấp cho bạn bất cứ thứ gì vừa được đẩy lên cách đây một giờ, và các khóa cấu hình bên dưới có thể không khớp với nó. v0.3.2 là tag hiện tại tính đến ngày 16 tháng 8 năm 2026.

sudo install -d -o "$USER" -g "$USER" /opt/sandbase
cd /opt/sandbase
git clone --branch v0.3.2 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build

Sử dụng npm ci, đừng dùng npm install. ci cài đặt chính xác các phiên bản được ghi trong lockfile đã commit, vì vậy cây thư mục của bạn sẽ khớp với cây thư mục mà các nhà phát triển đã kiểm thử. npm install được phép phân giải các phiên bản mới hơn, đó là cách một tag đã ghim âm thầm mất đi tính cố định.

Bây giờ hãy tạo một workspace. Workspace là một thư mục riêng biệt chứa các file agent và toàn bộ trạng thái runtime. Việc giữ nó nằm ngoài thư mục source checkout giúp bạn có thể pull một tag mới hơn mà không làm ảnh hưởng đến dữ liệu của mình.

mkdir -p /opt/sandbase/workspace
cd /opt/sandbase/workspace
node /opt/sandbase/sandbase-harness/dist/index.js init
node /opt/sandbase/sandbase-harness/dist/index.js start

init ghi một thư mục .managed-agents/ vào trong workspace. start khởi chạy console tại http://127.0.0.1:3000/dashboard và API tại http://127.0.0.1:3000/v1. Hiện tại bạn chưa thể truy cập từ laptop của mình, điều này là đúng và sẽ được đề cập chi tiết hơn ở phần dưới. Hãy truy cập console qua SSH tạm thời:

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

Đường dẫn node .../dist/index.js dài dòng đó sẽ gây bất tiện, vì vậy hãy đặt cho nó một cái tên.

alias sandbase='node /opt/sandbase/sandbase-harness/dist/index.js'

Các lệnh bên dưới được viết dưới dạng sandbase <command> dựa trên cơ sở đó.

Không cài đặt từ npm

Dự án đã nêu rõ điều này trong tài liệu cài đặt: gói managed-agents không định danh (unscoped) hiển thị trên npm không phải là dự án này. Do đó, npx managed-agents và npm install -g managed-agents sẽ tải về thứ gì đó không liên quan đến runtime mà bạn cần. Hãy cài đặt từ source trên GitHub đã được gắn tag cho đến khi các maintainer công bố một gói có định danh (scoped) chính thức. Đây không phải là một chú thích nhỏ trong lịch sử dự án: phiên bản v0.3.1 tồn tại chủ yếu để thay thế hướng dẫn quick start cũ trên npm bằng đường dẫn đến source đã được ghim tag.

Trỏ workspace vào một nhà cung cấp model

init ghi vào .managed-agents/config.yaml. Một nhà cung cấp được cấu hình cho toàn bộ workspace, sau đó các agent riêng lẻ sẽ chọn ID model cụ thể.

model:
  provider: openai
  api_key: ${OPENAI_API_KEY}
storage:
  metadata:
    provider: sqlite
    options: {}
  artifacts:
    provider: local
    options:
      base_path: files

Biểu mẫu ${OPENAI_API_KEY} lấy giá trị từ môi trường của tiến trình, vì vậy key không nằm trong file cấu hình và không bị đưa vào bất kỳ bản backup nào của file đó. Hãy đặt nó vào một file môi trường mà chỉ root mới có quyền đọc, vì systemd đọc EnvironmentFile= dưới quyền root trước khi nó hạ đặc quyền.

sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.env

Mở file đó bằng trình soạn thảo và thêm một dòng, OPENAI_API_KEY=sk-.... Các key của nhà cung cấp thuộc về đây. Các secret mà một agent sử dụng trong phiên làm việc nên nằm trong các vault chứa credential của runtime, đây là một vấn đề khác với phạm vi ảnh hưởng khác, và giữ secret bên ngoài các AI agent là tài liệu đáng đọc trước khi bạn dán một token production vào bất kỳ nơi nào trong hai vị trí này.

YAML của agent: mcp_servers, tools và các chính sách quyền hạn

Các agent được định nghĩa dưới dạng file YAML trong thư mục agents/ của workspace. Đây là phần runtime mà bạn sẽ thực sự dành thời gian làm việc. Các key sẽ dễ hiểu hơn sau khi bạn đã tự viết một vòng lặp agent đơn giản, vì mỗi key là một nút điều khiển cho những thứ mà bình thường bạn phải tự code: system prompt, danh sách tool và bước kiểm tra trước khi một tool được thực thi.

name: Incident commander
description: Triages alerts and coordinates response.
model: gpt-4o
system: |-
  You are an on-call incident commander.
mcp_servers:
  - name: sentry
    type: url
    url: https://mcp.sentry.dev/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy: { type: always_ask }
    configs:
      - name: bash
        permission_policy: { type: always_ask }
  - type: mcp_toolset
    mcp_server_name: sentry
metadata:
  template: incident-commander

Load file và kiểm tra xem nó đã được nạp chưa:

sandbase reload
sandbase list
sandbase chat agent_assistant --message "hello"

reload import file YAML seed vào SQLite. list lúc này sẽ in ra agent kèm theo ID. Nếu list không hiển thị agent, nghĩa là file chưa được parse, và .managed-agents/logs/runtime.log là nơi ghi lại lý do lỗi.

mcp_servers khai báo các endpoint MCP (model context protocol). type: url có nghĩa là runtime giao tiếp HTTP với một server chạy ở nơi khác, vì vậy mọi thứ bạn đang vận hành đều có thể dùng ở đây, bao gồm cả MCP server chạy trên cùng VPS với runtime. Web search thường là tool đầu tiên mọi người sử dụng, và bạn nên đọc cách cung cấp cho agent instance SearXNG của riêng bạn trước khi kết nối một instance, vì một tool trả về các trang do người lạ viết sẽ đưa văn bản không đáng tin cậy trực tiếp vào context của model. Cách kết nối đầu tiên an toàn hơn là dùng một endpoint chỉ đọc trên dữ liệu bạn đã sở hữu. Đây là cách openGym cung cấp endpoint bên cạnh chính ứng dụng theo dõi bài tập, để agent có thể trả lời câu hỏi về lịch sử tập luyện của bạn mà không thể sửa bất kỳ dữ liệu nào.

Việc khai báo một server không đồng nghĩa với việc cấp các tool của nó cho agent. Danh sách tools thực hiện điều đó, thông qua một entry mcp_toolset có mcp_server_name khớp với name ở trên. Nếu agent hoạt động như thể các tool MCP không tồn tại, hãy so sánh hai chuỗi đó từng ký tự một trước khi kiểm tra bất kỳ nơi nào khác.

agent_toolset_20260401 là tập hợp tool tích hợp sẵn. Hậu tố ngày tháng là phiên bản schema, vì vậy một agent được ghim vào phiên bản đó sẽ giữ nguyên các định nghĩa tool mà nó được viết dựa trên đó. default_config thiết lập chính sách cho mọi tool trong tập hợp, và mỗi entry dưới configs sẽ ghi đè lên một tool cụ thể theo tên, ví dụ như bash.

permission_policy là nơi runtime thể hiện giá trị vượt trội so với việc gọi model thuần túy. always_ask tạm dừng phiên làm việc và chờ con người phê duyệt lệnh gọi trước khi nó thực thi. always_allow cho phép lệnh đó chạy. Thiết lập bash thành always_ask nghĩa là agent không thể chạy lệnh shell nếu bạn chưa xem trước lệnh chính xác đó, đây cũng là cơ chế kiểm soát tương tự mà bạn sẽ cần khi chạy Claude Code an toàn trên VPS. Nếu bạn cũng chạy DeepSeek Harness, các cơ chế kiểm soát tương tự sẽ xuất hiện dưới dạng add-on thay vì các key YAML, và các plugin giới hạn ngân sách và kiểm soát lệnh gọi tool là thứ tương đương nhất với block này.

Ba chế độ sandbox và trường hợp sử dụng phù hợp

Các tool call thực thi mã nguồn sẽ chạy bên trong một sandbox. Backend được chọn theo từng môi trường, thông qua sandbox_provider trong đối tượng config của môi trường đó, hoặc tại mục Settings rồi đến Sandbox trong console. Các môi trường được tạo thông qua API tại POST /v1/environments.

local chạy mã nguồn như một tiến trình con của runtime, trên máy chủ, với quyền của chính người dùng chạy runtime. Đây là chế độ mặc định và phù hợp khi bạn là người dùng duy nhất và agent chỉ đọc các file bạn sở hữu. Nó không có tính cô lập. Một tool call xóa file sẽ xóa file của bạn, và một tool call đọc /etc/sandbase/runtime.env sẽ đọc key nhà cung cấp của bạn.

docker khởi chạy một container cho mỗi phiên làm việc.

{
  "sandbox_provider": "docker",
  "image": "node:22-slim",
  "resources": { "memory": "1g", "cpu": 1 }
}

Phiên làm việc có hệ thống file riêng, giới hạn bộ nhớ và CPU riêng, và container sẽ bị xóa khi phiên kết thúc. Hãy chuyển sang chế độ này ngay khi agent chạy mã nguồn mà bạn không phải là người viết. Chi phí là người dùng chạy runtime cần quyền truy cập vào Docker socket, và việc là thành viên của nhóm docker tương đương với quyền root trên máy chủ. Các container theo phiên có cấu trúc giống với sandbox cho agent tự host với một container mỗi lần chạy, vì vậy các lập luận về những gì một tiến trình thoát khỏi sandbox có thể truy cập cũng áp dụng tương tự tại đây.

kubernetes chạy workload của phiên làm việc dưới dạng một pod và điều khiển nó bằng kubectl exec và kubectl cp. Image của runtime cần có sẵn kubectl, và ServiceAccount của nó cần quyền RBAC (kiểm soát truy cập dựa trên vai trò) để tạo, xóa, lấy, liệt kê và theo dõi các pod trong namespace mục tiêu, cộng với subresource exec. Chế độ này chỉ đáng để thiết lập nếu bạn đã vận hành một cluster.

Tại sao runtime lại bind vào 127.0.0.1?

Vì nó khởi động với chế độ xác thực bị tắt. Runtime sẽ kích hoạt xác thực bằng bearer-token khi có ít nhất một API key tồn tại, và một init mới sẽ không tạo ra key nào cả. Việc bind vào 0.0.0.0 với cấu hình mặc định đó sẽ đặt một agent runtime không được xác thực, vốn đang nắm giữ các công cụ shell và provider key của bạn, trực tiếp lên internet công cộng.

Vì vậy, khi bạn muốn nó có thể truy cập được từ bên ngoài, hãy giữ nguyên địa chỉ bind và thực hiện hai việc sau.

Thứ nhất, bật xác thực lên. Thiết lập MANAGED_AGENTS_API_KEY trong file môi trường của service, hoặc tạo một key bằng POST /v1/api-keys, lệnh này sẽ trả về một trường secret_key đúng một lần duy nhất và không bao giờ hiển thị lại. Sau đó, các client phải gửi Authorization: Bearer <key> trong mỗi request. Một key tương ứng với một danh tính dùng chung, vì vậy nếu bạn thực sự muốn mỗi thành viên trong nhóm có một agent riêng biệt trong môi trường sandbox với các provider key được giữ tại một gateway duy nhất, OneCLI được xây dựng cho mô hình đó.

Thứ hai, đặt một reverse proxy ở phía trước và thực hiện TLS (transport layer security) termination tại đó. Runtime được thiết kế để phục vụ HTTP thuần và yêu cầu một thành phần khác xử lý chứng chỉ.

server {
    listen 443 ssl;
    server_name agents.example.com;

    ssl_certificate     /etc/letsencrypt/live/agents.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agents.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Hai trong số các dòng đó không phải là trang trí. proxy_buffering off rất quan trọng vì các phiên làm việc truyền dữ liệu qua server-sent events (SSE), và nếu bật buffering, nginx sẽ giữ phản hồi cho đến khi bộ đệm đầy, khiến console không hiển thị gì trong khi agent đang làm việc và sau đó đổ toàn bộ dữ liệu ra cùng lúc khi kết thúc. proxy_read_timeout 3600s rất quan trọng vì giá trị mặc định là 60 giây, nên một luồng dữ liệu im lặng quá một phút sẽ bị proxy đóng lại giữa chừng, và lỗi này trông giống như runtime bị crash.

Trên firewall, hãy mở cổng 22 và 443. Giữ cổng 3000 đóng, vì proxy truy cập vào nó qua loopback và không có gì bên ngoài server được phép truy cập trực tiếp vào đó.

Trỏ Anthropic SDK về máy chủ của bạn

Runtime này triển khai một bề mặt có dạng CMA /v1, vì vậy client Anthropic SDK có thể kết nối với nó bằng cách thay đổi một trường duy nhất.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
  baseURL: 'http://127.0.0.1:3000'
});

Nó cũng chấp nhận các beta header mà client Claude Managed Agents gửi, anthropic-beta: managed-agents-2026-04-01 và anthropic-beta: agent-memory-2026-07-22. Chúng là tùy chọn đối với runtime cục bộ. Chúng tồn tại để mã nguồn viết cho môi trường triển khai hosted có thể chạy mà không cần thay đổi tại đây.

Khả năng tương thích ở mức gần như hoàn toàn, nhưng không tuyệt đối. Hãy đọc docs/api-matrix.md trong bản checkout trước khi giả định một bề mặt nào đó tồn tại, vì dự án đã ghi lại các thiếu sót của chính nó tại đó, bao gồm cả các custom tool phía client, vốn vẫn cần đăng ký tên (named registration) bên trên giao thức event-result hiện tại.

HTTP thuần cũng hoạt động tốt và là cách nhanh nhất để xác minh runtime đang hoạt động:

curl -N -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello", "stream": true}'

Một phản hồi ổn định là một luồng sự kiện (stream of events) liên tục gửi về. Nếu kết nối bị ngắt, hãy tiếp tục từ sự kiện cuối cùng bạn nhận được thay vì phát lại toàn bộ lượt hội thoại:

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: EVENT_ID"

Luồng có thể tiếp tục (resumable stream) này là lý do tại sao một phiên làm việc vẫn tồn tại ngay cả khi bạn đóng laptop. Các sự kiện được lưu trữ trên server, vì vậy client đang phát lại một log thay vì giữ bản sao duy nhất.

Nơi lưu trữ thông tin xác thực, bộ nhớ và nhật ký kiểm toán trên đĩa

Mọi dữ liệu mà runtime sở hữu đều nằm trong .managed-agents/ tại thư mục làm việc.

.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/

data.db là metadata SQLite: các agent, phiên làm việc, mục trong kho lưu trữ thông tin xác thực, mục trong bộ nhớ và các API key.
files/ chứa các byte file đã tải lên và skills/ chứa các gói skill đã tải lên.
snapshots/ chứa các snapshot không gian làm việc của phiên, và sandbox/ chứa các thư mục làm việc của các phiên ở chế độ local.
logs/runtime.log là nơi đầu tiên cần kiểm tra bất cứ khi nào có tiến trình không phản hồi mà không báo lỗi.

Credential vault là các nhóm bí mật, mỗi nhóm được thêm vào bằng auth_type như environment_variable, và được gắn vào một phiên thông qua vault_ids khi phiên đó được tạo. Memory store chứa các mục được đặt tên mà bạn mount vào một phiên dưới dạng memory_store với thiết lập truy cập và hướng dẫn riêng. Cả hai đều nằm trong data.db, đây chính là điểm khác biệt giữa việc này và một lệnh gọi model thô: runtime ghi nhớ thông tin qua các phiên làm việc và ghi lại những gì đã xảy ra.

Vì tất cả nằm trong một thư mục, hãy sao lưu toàn bộ thư mục đó.

sudo systemctl stop sandbase
sudo tar czf /root/sandbase-$(date +%F).tgz -C /opt/sandbase/workspace .managed-agents
sudo systemctl start sandbase

Hãy dừng service trước. Việc sao chép cơ sở dữ liệu SQLite trong khi runtime đang ghi dữ liệu có thể tạo ra một file không thể mở được khi khôi phục, và bạn sẽ chỉ phát hiện ra điều đó vào đúng ngày cần dùng đến nó. Nếu bạn muốn giữ agent YAML trong git và lưu trạng thái ở nơi khác, tài liệu triển khai hỗ trợ ghim vị trí lưu trạng thái bằng --data-dir trên start.

Việc khôi phục diễn ra ngược lại: checkout cùng một tag trên một máy chủ mới, giải nén lưu trữ vào không gian làm việc, sau đó khởi động service. Provider key của bạn không nằm trong file lưu trữ nếu bạn sử dụng định dạng ${OPENAI_API_KEY}, vì vậy hãy lưu trữ key đó ở một nơi mà bạn chắc chắn vẫn còn giữ được.

Chạy dưới systemd

Hãy tạo một user riêng cho runtime để các lệnh gọi công cụ trong chế độ sandbox cục bộ không thể thực thi với quyền của bạn.

sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbase

Lưu file này dưới tên /etc/systemd/system/sandbase.service.

[Unit]
Description=SandBase Harness runtime
After=network-online.target

[Service]
User=sandbase
Group=sandbase
WorkingDirectory=/opt/sandbase/workspace
EnvironmentFile=/etc/sandbase/runtime.env
ExecStart=/usr/bin/node /opt/sandbase/sandbase-harness/dist/index.js start --host 127.0.0.1 --port 3000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Ví dụ triển khai của dự án gọi một binary managed-agents tại PATH. Việc cài đặt từ source có gắn tag không tự tạo file này, vì vậy ExecStart sẽ chạy node trực tiếp vào entry point đã build.

sudo systemctl daemon-reload
sudo systemctl enable --now sandbase
sudo systemctl status sandbase
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/dashboard

Kết quả ổn định là active (running) từ status và 200 từ curl. Nếu thấy kết quả khác, hãy đọc journalctl -u sandbase -n 50 trước và .managed-agents/logs/runtime.log sau. enable --now là phần quan trọng, vì tiến trình khởi chạy thủ công sẽ mất sau lần reboot tiếp theo.

Những lỗi thường gặp và thông báo tương ứng

npm run build bị kill mà npm không báo lỗi. Trên VPS 1 GB, tiến trình biên dịch TypeScript bị kernel out-of-memory killer dừng lại. Kernel ghi log lỗi này thay vì npm. Hãy xác nhận bằng journalctl -k | grep -i "out of memory", lệnh này sẽ in ra dòng thông báo tên tiến trình node bị kill. Hãy thêm swap, hoặc build trên instance lớn hơn rồi copy dist/ sang.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. Một tiến trình khác đang chiếm cổng. sudo ss -lntp | grep 3000 sẽ cho biết đó là tiến trình nào. Hãy dừng tiến trình đó hoặc khởi động runtime với --port 3001 và cập nhật proxy.

Dashboard không tải được từ laptop của bạn. Đây là hành vi mặc định vì runtime chỉ bind vào loopback. Hãy sử dụng SSH tunnel như hướng dẫn ở trên, hoặc hoàn thiện reverse proxy. Đừng sửa lỗi này bằng --host 0.0.0.0, vì xác thực sẽ bị tắt cho đến khi có key.

Docker sandbox bị lỗi permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock. Người dùng sandbase không nằm trong group docker. Hãy sửa bằng sudo usermod -aG docker sandbase và khởi động lại service. Lưu ý: group này có quyền root trên host, nên việc này làm giảm đi mục đích chạy runtime bằng user riêng.

Kubernetes sandbox bị lỗi Error from server (Forbidden). ServiceAccount thiếu quyền trên pod hoặc subresource exec. Kiểm tra trực tiếp bằng kubectl auth can-i create pods/exec -n <namespace>, lệnh này sẽ trả về yes hoặc no.

Mọi request đều trả về 401 sau khi bạn thêm API key. Xác thực được bật khi key đầu tiên tồn tại, nó áp dụng cho cả console và API. Hãy gửi Authorization: Bearer <key>. Nếu bạn làm mất key, hãy tạo key mới vì secret_key chỉ được hiển thị một lần và không được lưu trữ dưới dạng có thể đọc được.

Tools của MCP server không xuất hiện trong session. Kiểm tra mcp_server_name trong block tools so với name trong mcp_servers, sau đó kiểm tra xem runtime có thể truy cập URL đó từ chính server hay không bằng curl -i <url>. MCP server dạng URL là một dependency mạng, và VPS phân giải tên miền cũng như định tuyến lưu lượng khác với laptop của bạn.

FAQ

Tôi có thể chạy SandBase Harness mà không cần key của OpenAI hoặc Anthropic không?

Có, nếu bạn có một endpoint tương thích với OpenAI. Runtime hỗ trợ các nhà cung cấp OpenAI, Anthropic và các nhà cung cấp tương thích với OpenAI, vì vậy một máy chủ cục bộ hỗ trợ API OpenAI sẽ hoạt động. Hãy thiết lập nhà cung cấp workspace trong .managed-agents/config.yaml và trỏ api_key cùng endpoint vào đó. Runtime không bao gồm sẵn model nào, vì vậy cần có một dịch vụ để phản hồi các yêu cầu.

Có an toàn không khi mở runtime trên một cổng công khai?

Không, nếu để nguyên cấu hình mặc định. Nó bind vào 127.0.0.1:3000 và khởi chạy mà không bật xác thực, và giải pháp không phải là thay đổi địa chỉ bind. Hãy tạo một API key, hoặc thiết lập MANAGED_AGENTS_API_KEY để bật xác thực bằng bearer-token. Sau đó, đặt nginx hoặc Caddy phía trước để xử lý TLS, và đóng cổng 3000 trên firewall để đường truy cập duy nhất là thông qua proxy.

Sự khác biệt giữa sandbox cục bộ, Docker và Kubernetes là gì?

local chạy code công cụ như một tiến trình con của runtime trên host, với quyền của người dùng chạy runtime và không có sự cô lập. docker cấp cho mỗi phiên làm việc một container riêng với hệ thống file, giới hạn bộ nhớ và CPU share riêng, và xóa nó khi phiên làm việc kết thúc. kubernetes chạy phiên làm việc dưới dạng một pod và điều khiển nó bằng kubectl exec, yêu cầu kubectl bên trong image của runtime và RBAC trên các pod cộng với subresource exec trong namespace đích.

Chính xác thì tôi cần sao lưu những gì?

Thư mục .managed-agents/ trong workspace. Nó chứa config.yaml, cơ sở dữ liệu SQLite data.db với các agent, phiên làm việc, mục nhập trong kho lưu trữ credential và bộ nhớ, cùng với các file đã tải lên, gói kỹ năng và snapshot của phiên làm việc. Hãy dừng dịch vụ trước khi sao chép để SQLite không bị ghi dữ liệu trong quá trình lưu trữ. Các API key của nhà cung cấp được tham chiếu dưới dạng ${OPENAI_API_KEY} không nằm trong bản sao lưu, vì vậy hãy lưu trữ chúng riêng biệt.

Tại sao nên clone tag v0.3.2 thay vì nhánh main?

Một tag là một cây thư mục cố định, vì vậy các key cấu hình và lệnh CLI mà bạn đọc được chính là những gì bạn nhận được. main thay đổi liên tục, và một key cấu hình có thể bị đổi tên giữa thời điểm hướng dẫn được viết và thời điểm bạn thực hiện. Dự án cũng cảnh báo rằng gói managed-agents không định danh trên npm không phải là dự án này, vì vậy npx managed-agents sẽ cài đặt một thứ không liên quan. Bản release v0.3.1 tồn tại chủ yếu để thay thế hướng dẫn cài đặt nhanh qua npm đó bằng đường dẫn source đã được ghim theo tag.

#ai-agents #mcp #tự lưu trữ #sandboxing#anthropic-sdk