Bởi Matt Connor 2026-08-16

Hướng dẫn tự host SandBase Harness v0.3.2 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ên nếu để nguyên cấu hình mặc định. Nó bind vào 127.0.0.1:3000 và khởi động mà không có xác thực, và cách khắc phục không phải là đổ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 filesystem, 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 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: Tôi cần sao lưu chính xác 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 vault thông tin xác thực 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 chi tiết cách tự host SandBase Harness v0.3.2 trên VPS Ubuntu. Bạn sẽ nắm được quy trình cài đặt, cấu hình file agent YAML, MCP servers và trỏ Anthropic SDK về server riêng.

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

Tự host runtime của SandBase agent nghĩa là chạy SandBase Harness trên máy chủ do bạn sở hữu, 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 ổ đĩa 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 một /v1 HTTP API và 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 hướng: bạn có thể viết code dựa trên Anthropic SDK và trỏ baseURL của nó về máy chủ của riêng 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 một 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 dùng container sandbox cho từng phiên làm việc.

Ubuntu 24.04 cung cấp Node 18.19 trong repository mặc định, 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 sẽ in ra v22 hoặc cao hơn và npm -v sẽ in ra 10 hoặc cao hơn. Nếu node -v vẫn in ra 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ẽ chạy dựa trên phiên bản node mà shell tìm thấy đầu tiên.

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

Hãy cài đặt từ một tag, không bao giờ cài từ một branch đang thay đổi. Một bản clone thuần túy của main sẽ lấy về 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, khô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 khớp với cây thư mục mà các maintainer đã kiểm thử. npm install được phép phân giải các phiên bản mới hơn, đây là cách mà 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ó bên 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 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 bê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 đó rất 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ế cách bắt đầu nhanh qua npm cũ 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ị sao lưu cùng với 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ề nơi nà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 kho lưu trữ 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à bài viết đá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.

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

Tải nó lên và kiểm tra xem nó đã được nạp chưa:

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

reload nhập file YAML gốc vào SQLite. list lúc này sẽ in ra agent kèm theo ID. Nếu list không hiển thị nó, nghĩa là file chưa được phân tích cú pháp, và .managed-agents/logs/runtime.log là nơi ghi lại lý do.

mcp_servers khai báo các endpoint MCP (model context protocol). type: url có nghĩa là runtime giao tiếp qua HTTP với một server chạy ở nơi khác, vì vậy bất cứ thứ gì bạn đang vận hành đều hoạt động ở đây, bao gồm cả các MCP server được host trên cùng VPS với runtime.

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 mục 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 tìm kiếm ở 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 đó 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 mục dưới configs sẽ ghi đè lên một tool 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 nó chạy. Việc đặt bash thành always_ask nghĩa là agent không thể chạy lệnh shell nếu bạn chưa thấy chính xác lệnh đó trước, đây cũng là quyền kiểm soát tương tự mà bạn sẽ cần khi chạy Claude Code một cách an toàn trên VPS.

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

Các lệnh gọi tool 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 trong mục Settings rồi đến Sandbox trên 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 host, 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 mà bạn sở hữu. Chế độ này không có tính cô lập. Một lệnh gọi tool xóa file sẽ xóa file của bạn, và một lệnh gọi tool đọ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à hạn mức CPU riêng, và container sẽ bị xóa khi phiên làm việc 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 host. Các container theo phiên có cấu trúc giống với sandbox 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 runtime cần có sẵn kubectl, và ServiceAccount của nó cần quyền RBAC (role-based access control) để tạo, xóa, lấy, liệt kê và theo dõi các pod trong namespace đích, 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 bản cài đặt mới init sẽ không tạo ra key nào. Việc bind vào 0.0.0.0 với cấu hình mặc định đó sẽ đưa một agent runtime không được xác thực, vốn đang nắm giữ các shell tool và provider key của bạn, ra ngoài 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.

Đầu tiên, hãy bật xác thực. 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 duy nhất một lần 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.

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à khi bật buffering, nginx sẽ giữ phản hồi cho đến khi bộ đệm đầy. Kết quả là console không hiển thị gì trong khi agent đang làm việc, rồi sau đó mới đổ toàn bộ dữ liệu ra cùng lú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 nó qua loopback và không có gì bên ngoài máy chủ cần kết nối tới cổng này.

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. Các header này 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 phải 100%. Hãy đọc docs/api-matrix.md trong bản checkout trước khi giả định rằng một bề mặt nào đó tồn tại, vì dự án đã ghi lại các hạn chế 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 phía 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 để kiểm tra xem runtime có đang hoạt động hay khô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 bình thường là một luồng sự kiện (stream of events) liên tục gửi đến. 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 truy vấn:

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) đó 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 workspace.

.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à 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 workspace của phiên làm việc, và sandbox/ chứa thư mục làm việc của các phiên chạy ở chế độ local.
logs/runtime.log là nơi đầu tiên cần kiểm tra bất cứ khi nào hệ thống im lặng không phản hồ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 làm việc 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 phiên làm việc 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 thuần túy: runtime ghi nhớ thông tin giữa các phiên 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ữ file YAML của agent 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 workspace, rồi 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 đó ở nơi bạn có thể truy cập đượ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ạo ra 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ả bình thường 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 bạn sẽ thấy

npm run build bị kill mà không có lỗi từ npm. Trên VPS 1 GB, quá trình biên dịch TypeScript bị kernel out-of-memory killer dừng lại, nó báo lỗi vào log của kernel thay vì npm. 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 đã chiếm cổng này. sudo ss -lntp | grep 3000 sẽ cho biết tên tiến trình đó. 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 dùng SSH tunnel như hướng dẫn ở trên, hoặc hoàn tất cấu hình reverse proxy. Đừng cố sửa 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 vớ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. Khắc phục bằng sudo usermod -aG docker sandbase và khởi động lại service. Hãy hiểu rõ quyền bạn vừa cấp: group đó tương đương root trên host, nó làm mất đi một phần lý do bạn tạo user riêng cho runtime.

Kubernetes sandbox bị lỗi với Error from server (Forbidden). ServiceAccount thiếu quyề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 thì hãy tạo key mới, vì secret_key chỉ được trả về một lần duy nhất 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 bằng curl -i <url> hay không. 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 traffic 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 bạn cần 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ên nếu để nguyên cấu hình mặc định. Nó bind vào 127.0.0.1:3000 và khởi động mà không có xác thực, và cách khắc phục không phải là đổ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 filesystem, 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 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.

Tôi cần sao lưu chính xác 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 vault thông tin xác thực 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 sẽ nhận được. main thường thay đổi, và một key cấu hình có thể bị đổi tên trong khoảng thời gian từ lúc hướng dẫn được viết đến lúc bạn thực hiện. Dự án cũng cảnh báo rằng gói managed-agents không có scope 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ế cách cài đặt nhanh qua npm đó bằng đường dẫn source đã được ghim tag.

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