Cara Self-Host SandBase Agent Runtime pada VPS
Panduan lengkap menjalankan SandBase Harness v0.3.8 pada pelayan sendiri. Ketahui cara konfigurasi fail YAML, tetapan mod sandbox, pelayan MCP dan integrasi Anthropic SDK.
Apa yang anda peroleh apabila melakukan self-hosting runtime ejen SandBase
Melakukan self-hosting runtime ejen SandBase bermaksud menjalankan SandBase Harness pada pelayan milik anda sendiri, supaya sesi, kelayakan, memori dan jejak audit tersimpan pada cakera anda dan bukannya milik pihak lain. Ia merupakan servis Node. Ia mendengar pada 127.0.0.1:3000, menyediakan API HTTP /v1 serta konsol web, dan menyimpan statusnya dalam SQLite bersebelahan dengan fail ejen anda.
API /v1 dibentuk mengikut Claude Managed Agents (CMA), iaitu API ejen terurus yang dihoskan. Inilah yang menjadikan runtime ini menarik dalam kedua-dua arah: anda boleh menulis kod menggunakan Anthropic SDK dan menghalakan baseURL miliknya ke pelayan anda sendiri, kemudian memindahkan kod yang sama ke persekitaran yang dihoskan pada masa akan datang.
SandBase Harness tidak menyertakan model. Ia memanggil model tersebut. Setakat 12 Oktober 2026, ia menyokong OpenAI, Anthropic, MiniMax dan endpoint yang serasi dengan OpenAI, yang merangkumi gateway yang dihoskan sendiri serta penyedia seperti DeepSeek V4. MiniMax telah diperkenalkan sebagai penyedia kelas pertama dalam v0.3.3, dengan pilihan endpoint global atau tanah besar China. Anda masih perlu menyediakan API key, atau pelayan tempatan yang menggunakan API OpenAI.
Keperluan sebelum bermula
- Sebuah VPS yang menjalankan Ubuntu 24.04 dengan sekurang-kurangnya 2 GB RAM. Proses binaan TypeScript merupakan langkah paling berat dalam pemasangan ini.
- Node.js 22 atau lebih baharu, dan npm 10 atau lebih baharu. Kedua-duanya adalah keperluan minimum yang ditetapkan oleh projek ini.
git, berserta kunci API bagi penyedia model yang anda rancang untuk gunakan.- Docker, tetapi hanya jika anda mahukan sandbox kontena bagi setiap sesi.
Ubuntu 24.04 membekalkan Node 18.19 dalam repositorinya sendiri, yang berada di bawah tahap minimum, jadi ambil Node daripada NodeSource sebaliknya.
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -vnode -v sepatutnya memaparkan v22 atau lebih tinggi dan npm -v sepatutnya memaparkan 10 atau lebih tinggi. Jika node -v masih memaparkan v18.19.1, pakej pengedaran tersebut masih terpasang dan diutamakan dalam PATH. Buang pakej tersebut sebelum anda meneruskan, kerana proses binaan akan dijalankan menggunakan node yang ditemui oleh shell.
Pasang SandBase daripada tag v0.3.8
Pasang daripada tag, jangan sekali-kali daripada cawangan yang berubah-ubah. Clone kosong bagi main memberikan anda apa sahaja yang dimasukkan sejam yang lalu, dan kunci konfigurasi di bawah mungkin tidak sepadan dengannya. v0.3.8, yang diterbitkan pada 30 Ogos 2026, ialah tag semasa setakat 12 Oktober 2026, dan ia merupakan tag yang ditetapkan dalam dokumentasi pemasangan projek itu sendiri.
sudo install -d -o "$USER" -g "$USER" /opt/sandbase
cd /opt/sandbase
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run buildGunakan npm ci, bukan npm install. ci memasang versi tepat yang direkodkan dalam lockfile yang dikomit, supaya pepohon anda sepadan dengan pepohon yang diuji oleh penyelenggara. npm install dibenarkan untuk menyelesaikan versi yang lebih baharu, yang merupakan cara tag yang ditetapkan secara senyap-senyap berhenti menjadi tag yang ditetapkan.
Sekarang, cipta ruang kerja (workspace). Ruang kerja ialah direktori berasingan yang menyimpan fail ejen anda dan semua status masa jalan, dan menyimpannya di luar checkout sumber bermakna anda boleh menarik tag yang lebih baharu tanpa menjejaskan data anda.
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 startinit menulis direktori .managed-agents/ ke dalam ruang kerja. start memulakan konsol pada http://127.0.0.1:3000/dashboard dan API pada http://127.0.0.1:3000/v1. Kedua-duanya belum boleh dicapai daripada komputer riba anda lagi, ini adalah betul dan akan dibincangkan dengan lebih lanjut di bawah. Capai konsol melalui SSH buat masa ini:
ssh -N -L 3000:127.0.0.1:3000 you@your-serverLaluan node .../dist/index.js yang panjang itu memenatkan, jadi berikan nama kepadanya.
alias sandbase='node /opt/sandbase/sandbase-harness/dist/index.js'Perintah di bawah ditulis sebagai sandbase <command> berdasarkan perkara tersebut.
Jangan pasang daripada npm
Projek ini menyatakan perkara berikut dalam dokumentasi pemasangannya sendiri: pakej managed-agents tanpa skop yang kelihatan di npm bukanlah projek ini. Oleh itu, npx managed-agents dan npm install -g managed-agents akan mengambil sesuatu yang tidak berkaitan dengan runtime yang anda inginkan. Pasang daripada sumber GitHub yang bertanda (tagged) sehingga penyelenggara mengumumkan pakej rasmi yang mempunyai skop. Ini bukan sekadar nota kaki kecil dalam sejarah projek ini: v0.3.1 wujud terutamanya untuk menggantikan panduan permulaan pantas npm yang lama dengan laluan sumber bertanda yang telah ditetapkan (pinned).
Halakan ruang kerja kepada penyedia model
init menulis .managed-agents/config.yaml. Satu penyedia dikonfigurasikan untuk keseluruhan ruang kerja, dan ejen individu kemudian memilih ID model yang konkrit.
model:
provider: openai
api_key: ${OPENAI_API_KEY}
storage:
metadata:
provider: sqlite
options: {}
artifacts:
provider: local
options:
base_path: filesBorang ${OPENAI_API_KEY} mengambil nilai daripada persekitaran proses, jadi kunci tersebut kekal di luar fail konfigurasi dan di luar setiap sandaran yang anda buat bagi fail tersebut. Letakkannya dalam fail persekitaran yang hanya boleh dibaca oleh root, memandangkan systemd membaca EnvironmentFile= sebagai root sebelum ia menurunkan keistimewaan (drop privileges).
sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.envBuka fail tersebut dalam editor dan tambah satu baris, OPENAI_API_KEY=sk-.... Kunci penyedia perlu diletakkan di sini. Rahsia yang digunakan oleh ejen semasa sesi perlu diletakkan dalam peti simpanan kelayakan (credential vaults) runtime, yang merupakan masalah berbeza dengan radius impak yang berbeza, dan menjauhkan rahsia daripada ejen AI adalah wajar dibaca sebelum anda menampal token pengeluaran (production token) ke dalam mana-mana lokasi tersebut.
YAML ejen: mcp_servers, tools dan polisi kebenaran
Ejen ditakrifkan sebagai fail YAML dalam direktori ruang kerja agents/. Ini adalah bahagian runtime yang akan anda gunakan dengan kerap. Kunci-kunci tersebut lebih mudah difahami setelah anda menulis gelung ejen kecil secara manual, kerana setiap satunya merupakan kawalan bagi fungsi yang sepatutnya anda kodkan sendiri: prompt sistem, senarai alat, dan semakan yang dijalankan sebelum sesuatu alat diaktifkan.
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-commanderMuatkan ia dan pastikan ia telah berjaya disimpan:
sandbase reload
sandbase list
sandbase chat agent_assistant --message "hello"reload mengimport YAML benih ke dalam SQLite. list kini sepatutnya memaparkan ejen tersebut berserta ID. Jika list tidak menunjukkannya, fail tersebut gagal diurai, dan .managed-agents/logs/runtime.log adalah tempat di mana puncanya dicatatkan.
mcp_servers mengisytiharkan endpoint MCP (model context protocol). type: url bermaksud runtime berkomunikasi melalui HTTP dengan pelayan yang berjalan di tempat lain, jadi apa-apa yang anda kendalikan sekarang akan berfungsi di sini, termasuk pelayan MCP yang dihoskan pada VPS yang sama dengan runtime tersebut. Carian web biasanya merupakan alat pertama yang dicari oleh pengguna, dan memberikan ejen akses kepada instance SearXNG anda sendiri adalah bacaan yang disyorkan sebelum anda menyambungkannya, kerana alat yang mengembalikan halaman daripada pihak luar akan memasukkan teks yang tidak dipercayai terus ke dalam konteks model. Langkah permulaan yang lebih selamat adalah sebaliknya, iaitu endpoint baca-sahaja (read-only) ke atas data milik anda sendiri, seperti yang dilakukan oleh openGym yang mendedahkan data di sebelah penjejak senaman itu sendiri, supaya ejen boleh menjawab soalan tentang sejarah latihan anda tanpa keupayaan untuk mengubah suai mana-mana data tersebut.
Mengisytiharkan pelayan tidak bermakna alatnya terus diberikan kepada ejen. Senarai tools melakukan perkara itu, melalui entri mcp_toolset yang mana mcp_server_name-nya sepadan dengan name di atas. Jika ejen berkelakuan seolah-olah alat MCP tidak wujud, bandingkan kedua-dua rentetan tersebut aksara demi aksara sebelum anda memeriksa tempat lain.
agent_toolset_20260401 ialah set alat terbina dalam. Akhiran bertarikh adalah versi skema, jadi ejen yang ditetapkan kepadanya akan mengekalkan definisi alat yang digunakan semasa ia ditulis. default_config menetapkan polisi untuk setiap alat dalam set tersebut, dan setiap entri di bawah configs akan mengatasi satu alat mengikut nama, iaitu bash dalam contoh tersebut.
permission_policy adalah tempat di mana runtime membuktikan nilainya berbanding panggilan model biasa. always_ask menjeda sesi dan menunggu manusia meluluskan panggilan tersebut sebelum ia dijalankan. always_allow membenarkannya diteruskan. Menetapkan bash kepada always_ask bermaksud ejen tidak boleh menjalankan arahan shell tanpa anda melihat arahan tepat tersebut terlebih dahulu, yang merupakan kawalan yang sama yang anda akan gunakan apabila menjalankan Claude Code dengan selamat pada VPS. Jika anda juga menjalankan DeepSeek Harness, kawalan yang sama akan tiba di sana sebagai add-on dan bukannya sebagai kunci YAML, dan pemalam yang mengehadkan bajet serta mengawal panggilan alat adalah setara yang paling hampir dengan blok ini.
Empat mod sandbox dan kesesuaian penggunaannya
Panggilan alat yang melaksanakan kod dijalankan di dalam sandbox. Backend dipilih mengikut persekitaran, melalui sandbox_provider dalam objek config persekitaran tersebut, atau ditetapkan sebagai lalai ruang kerja dalam konsol di bawah Settings, dalam editor Sandbox di bawah Advanced. Persekitaran dicipta melalui API di POST /v1/environments.
local menjalankan kod sebagai proses anak bagi runtime, pada hos, sebagai pengguna runtime itu sendiri. Ini adalah tetapan lalai apabila sesuatu persekitaran tidak menamakan backend, dan ia munasabah apabila anda adalah satu-satunya pengguna dan ejen hanya membaca fail milik anda. Persekitaran yang menamakan backend yang tidak dapat dimuatkan oleh runtime akan ditolak dan bukannya dijalankan secara senyap di sini. Ia bukan pengasingan. Panggilan alat yang memadam fail akan memadam fail anda, dan panggilan alat yang membaca /etc/sandbase/runtime.env akan membaca kunci pembekal anda.
docker memulakan satu kontena bagi setiap sesi.
{
"sandbox_provider": "docker",
"image": "node:22-slim",
"resources": { "memory": "1g", "cpu": 1 }
}Sesi tersebut mendapat sistem failnya sendiri, dan kontena akan dibuang bersama sesi tersebut. Had memori dan CPU bukan sebahagian daripada mod ini: runtime menambah --memory dan --cpus pada kontena hanya apabila blok resources persekitaran menetapkannya, seperti dalam contoh, jadi persekitaran tanpa blok tersebut mendapat kontena tanpa had tersendiri. Jika image ditinggalkan, runtime akan menggunakan ghcr.io/sandbaseai/sandbase-harness-sandbox:latest. Beralihlah kepada mod ini sebaik sahaja ejen menjalankan kod yang tidak ditulis oleh anda. Kosnya ialah pengguna runtime memerlukan akses kepada soket Docker, dan keahlian dalam kumpulan docker adalah setara dengan root pada hos. Kontena bagi setiap sesi mempunyai bentuk yang sama seperti sandbox ejen yang dihoskan sendiri dengan satu kontena bagi setiap pelaksanaan, jadi penaakulan tentang perkara yang boleh dicapai oleh proses yang terlepas terpakai di sini tanpa perubahan.
kubernetes menjalankan beban kerja sesi sebagai pod dan memacunya dengan kubectl exec dan kubectl cp. Imej runtime memerlukan kubectl tersedia, dan ServiceAccount-nya memerlukan kebenaran RBAC (kawalan akses berasaskan peranan) untuk mencipta, memadam, mendapatkan, menyenaraikan dan memantau pod dalam namespace sasaran, serta subsumber exec. Mod ini hanya berbaloi untuk disediakan jika anda sudah menjalankan kluster.
self-hosted worker dinamakan remote dalam Settings dan self_hosted dalam Environment, dan ia tidak menjalankan kod alat pada kotak ini sama sekali. Runtime meletakkan kerja tersebut pada baris gilir, dan pekerja luaran, yang diberikan URL API pekerja dan kunci daripada Settings, akan menuntut dan melengkapkan item yang beratur di luar hos. Ia sesuai apabila kod perlu dijalankan pada mesin yang tidak menyimpan kunci pembekal anda. Had sumber hanya dipatuhi oleh docker dan kubernetes, jadi mengehadkan pekerja adalah tugas hos pekerja tersebut.
Mengapa runtime terikat pada 127.0.0.1?
Kerana ia bermula dengan pengesahan dimatikan. Runtime mendayakan pengesahan bearer-token apabila sekurang-kurangnya satu API key wujud, dan init yang baharu tidak mencipta sebarang kunci. Mengikat pada 0.0.0.0 dengan tetapan lalai tersebut akan meletakkan runtime ejen yang tidak disahkan, yang memegang alat shell dan kunci pembekal anda, pada internet awam.
Jadi, apabila anda mahu ia boleh dicapai, biarkan alamat ikatan (bind address) seperti asal dan lakukan dua perkara lain.
Pertama, hidupkan pengesahan. Tetapkan MANAGED_AGENTS_API_KEY dalam fail persekitaran servis, atau cipta kunci dengan POST /v1/api-keys, yang akan memaparkan medan secret_key sekali sahaja dan tidak akan menunjukkannya lagi. Pelanggan kemudian menghantar Authorization: Bearer <key> pada setiap permintaan API, atau kunci yang sama sebagai x-api-key, tetapi jangan gunakan kedua-duanya serentak. Kunci tersebut melindungi API, bukan konsol: halaman papan pemuka dan aset statiknya dimuatkan tanpa kunci, begitu juga dengan /v1/x/health dan /v1/x/metrics. Satu kunci adalah satu identiti yang dikongsi, jadi jika apa yang anda sebenarnya mahukan ialah ejen berasingan yang dipasirkan (sandboxed) bagi setiap ahli pasukan dengan kunci pembekal disimpan dalam satu gateway, OneCLI dibina untuk bentuk tersebut.
Kedua, letakkan reverse proxy di hadapan dan tamatkan TLS (transport layer security) di sana. Runtime menyediakan HTTP biasa secara reka bentuk dan menjangkakan sesuatu yang lain untuk mengendalikan sijil.
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;
}
}Dua daripada baris tersebut bukan sekadar hiasan. proxy_buffering off penting kerana sesi distrim melalui server-sent events (SSE), dan dengan penimbalan (buffering) dihidupkan, nginx menahan respons sehingga penimbalnya penuh, menyebabkan konsol tidak memaparkan apa-apa semasa ejen bekerja dan kemudian memaparkan segala-galanya di akhir proses. proxy_read_timeout 3600s penting kerana nilai lalai ialah 60 saat, jadi strim yang senyap melebihi satu minit akan ditutup oleh proksi di tengah-tengah giliran, dan kegagalan tersebut kelihatan seperti runtime yang terhempas.
Pada firewall, buka port 22 dan 443. Biarkan 3000 tertutup, kerana proksi mencapainya melalui loopback dan tiada apa-apa di luar kotak tersebut yang sepatutnya boleh mengaksesnya. Kerana /v1/x/metrics menjawab tanpa kunci, tambahkan location = /v1/x/metrics { return 404; } pada blok pelayan jika anda tidak mahu menerbitkan metrik runtime.
Halakan SDK Anthropic ke pelayan anda sendiri
Runtime ini melaksanakan permukaan berbentuk CMA /v1, jadi klien SDK Anthropic berhubung dengannya dengan satu medan diubah.
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'
});Ia juga menerima pengepala beta yang dihantar oleh klien Claude Managed Agents, anthropic-beta: managed-agents-2026-04-01 dan anthropic-beta: agent-memory-2026-07-22. Permintaan biasa tanpa pengepala keserasian diterima sebagai pemanggil tempatan. Permintaan yang membawa x-api-key, anthropic-version atau anthropic-beta tertakluk kepada peraturan yang dihoskan: versi 2023-06-01 dan beta managed-agents diperlukan, kecuali laluan /v1/memory_stores memerlukan beta agent-memory dan menolak kedua-duanya jika digabungkan. Pengepala ini wujud supaya kod yang ditulis untuk penempatan yang dihoskan boleh dijalankan tanpa perubahan di sini.
Keserasian adalah hampir, bukan menyeluruh. Baca docs/api-matrix.md dalam checkout sebelum anda menganggap sesuatu permukaan itu wujud, kerana projek tersebut mendokumenkan jurangnya sendiri di sana, termasuk alatan tersuai sebelah klien, yang masih memerlukan pendaftaran bernama di atas protokol hasil-acara semasa.
HTTP biasa berfungsi dengan baik, dan merupakan cara terpantas untuk membuktikan runtime tersebut aktif:
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}'Respons yang sihat ialah aliran acara yang terus tiba. Jika sambungan terputus, sambung semula daripada acara terakhir yang anda lihat dan bukannya memainkan semula keseluruhan giliran:
curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
-H "Last-Event-ID: EVENT_ID"Aliran yang boleh disambung semula itulah sebabnya sesi bertahan walaupun komputer riba ditutup. Acara tersebut dikekalkan pada pelayan, jadi klien memainkan semula log dan bukannya memegang satu-satunya salinan.
Tempat kelayakan, memori dan jejak audit disimpan pada cakera
Segala milik runtime berada di bawah .managed-agents/ dalam ruang kerja.
.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/data.dbialah metadata SQLite: ejen, sesi, entri peti kelayakan, entri stor memori dan kunci API.files/menyimpan bait fail yang dimuat naik danskills/menyimpan pakej kemahiran yang dimuat naik.snapshots/menyimpan syot kilas ruang kerja sesi, dansandbox/menyimpan direktori kerja bagi sesi mod tempatan.logs/runtime.logialah tempat pertama untuk diperiksa apabila sesuatu perkara tidak menunjukkan sebarang tindak balas.
Peti kelayakan ialah kumpulan rahsia, setiap satunya ditambah dengan auth_type seperti environment_variable, dan dilampirkan pada sesi melalui vault_ids apabila sesi dicipta. Stor memori menyimpan entri bernama yang anda lekapkan ke dalam sesi sebagai memory_store dengan tetapan akses dan arahannya sendiri. Kedua-duanya berada dalam data.db, yang merupakan perbezaan tepat antara ini dengan panggilan model mentah: runtime mengingati merentas sesi, dan ia merekodkan apa yang berlaku.
Oleh kerana ia merupakan satu direktori, buat sandaran sebagai satu unit.
sudo systemctl stop sandbase
sudo tar czf /root/sandbase-$(date +%F).tgz -C /opt/sandbase/workspace .managed-agents
sudo systemctl start sandbaseHentikan servis terlebih dahulu. Menyalin pangkalan data SQLite semasa runtime sedang menulis kepadanya boleh menghasilkan fail yang tidak dapat dibuka semasa pemulihan, dan anda hanya akan mengetahuinya pada hari anda memerlukannya. Jika anda lebih suka menyimpan YAML ejen dalam git dan keadaan (state) di tempat lain, dokumen penempatan menyokong penetapan lokasi keadaan dengan --data-dir pada start.
Pemulihan adalah sebaliknya: semak tag yang sama pada mesin baharu, nyahpek arkib ke dalam ruang kerja, kemudian mulakan servis. Kunci pembekal anda tidak berada dalam arkib jika anda menggunakan borang ${OPENAI_API_KEY}, jadi simpan kunci tersebut di tempat yang anda boleh akses kemudian.
Jalankan di bawah systemd
Berikan runtime pengguna sendiri supaya panggilan alat dalam mod sandbox tempatan tidak boleh bertindak sebagai anda.
sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbaseSimpan ini sebagai /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.targetContoh penempatan projek itu sendiri memanggil binari managed-agents pada PATH. Pemasangan daripada sumber bertag tidak mencipta binari tersebut, jadi ExecStart menjalankan node terhadap titik masuk (entry point) yang dibina sebagai ganti.
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/dashboardHasil yang sihat ialah active (running) daripada status dan 200 daripada curl. Jika mendapat hasil lain, baca journalctl -u sandbase -n 50 dahulu dan .managed-agents/logs/runtime.log kemudian. enable --now ialah bahagian yang penting, kerana proses yang dimulakan secara manual akan hilang selepas but semula (reboot) yang seterusnya.
Apa yang tergendala, dan mesej yang akan anda lihat
npm run build ditamatkan tanpa ralat daripada npm. Pada VPS 1 GB, kompilasi TypeScript dihentikan oleh kernel out-of-memory killer, yang melaporkannya ke log kernel dan bukannya kepada npm. Sahkan dengan journalctl -k | grep -i "out of memory", yang mencetak baris yang menamakan proses node yang telah ditamatkan. Tambah swap, atau bina pada instans yang lebih besar dan salin dist/ ke destinasi.
Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. Proses lain sudah memegang port tersebut. sudo ss -lntp | grep 3000 menamakan proses itu. Sama ada hentikan proses tersebut atau mulakan runtime dengan --port 3001 dan kemas kini proksi.
Papan pemuka tidak dimuatkan daripada komputer riba anda. Itu adalah tingkah laku yang dijangkakan, kerana runtime terikat pada loopback. Gunakan terowong SSH di atas, atau selesaikan konfigurasi reverse proxy. Jangan baiki dengan --host 0.0.0.0, kerana pengesahan dimatikan sehingga kunci wujud.
Sandbox Docker gagal dengan permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock. Pengguna sandbase tiada dalam kumpulan docker. Betulkan dengan sudo usermod -aG docker sandbase dan mulakan semula servis, dan fahami apa yang anda berikan: kumpulan itu adalah root pada hos, jadi ia membatalkan sebahagian daripada sebab anda memberikan runtime pengguna sendiri.
Sandbox Kubernetes gagal dengan Error from server (Forbidden). ServiceAccount kehilangan kebenaran pod atau sub-sumber exec. Semak secara terus dengan kubectl auth can-i create pods/exec -n <namespace>, yang menjawab yes atau no.
Permintaan API mengembalikan 401 selepas anda menambah kunci API. Pengesahan dihidupkan apabila kunci pertama wujud, dan ia meliputi API tetapi bukan konsol: halaman papan pemuka dan aset statiknya kekal awam, jadi konsol terus dimuatkan dan kemudian memerlukan kunci untuk panggilan API-nya. Hantar Authorization: Bearer <key> atau x-api-key: <key>, bukan kedua-duanya, kerana permintaan yang membawa kedua-dua pengepala akan ditolak dengan 401 walaupun pengesahan dimatikan. Jika anda kehilangan kunci, cipta kunci baharu, kerana secret_key dikembalikan sekali sahaja dan disimpan hanya sebagai hash.
Alatan pelayan MCP tidak pernah muncul dalam sesi. Semak mcp_server_name dalam blok tools berbanding name dalam mcp_servers, kemudian semak sama ada runtime boleh mencapai URL tersebut daripada pelayan itu sendiri dengan curl -i <url>. Pelayan MCP jenis URL ialah dependency rangkaian, dan VPS menyelesaikan nama serta menghalakan trafik secara berbeza daripada komputer riba anda.
FAQ
Bolehkah saya menjalankan SandBase Harness tanpa kunci OpenAI atau Anthropic?
Boleh, dengan kunci MiniMax atau endpoint yang serasi dengan OpenAI. Runtime ini menyokong penyedia OpenAI, Anthropic, MiniMax dan penyedia yang serasi dengan OpenAI, jadi pelayan tempatan yang menggunakan API OpenAI boleh berfungsi. Tetapkan penyedia ruang kerja dalam .managed-agents/config.yaml dan halakan api_key serta endpoint kepadanya. Runtime ini tidak menyertakan model sendiri, jadi sesuatu perlu menjawab panggilan tersebut.
Adakah selamat untuk mendedahkan runtime pada port awam?
Tidak seperti yang dipasang secara lalai. Ia mengikat pada 127.0.0.1:3000 dan bermula dengan pengesahan dimatikan, dan penyelesaiannya bukan sekadar menukar alamat ikat. Cipta kunci API, atau tetapkan MANAGED_AGENTS_API_KEY, supaya pengesahan bearer-token diaktifkan untuk API tersebut. Kemudian, letakkan nginx atau Caddy di hadapan untuk TLS, dan pastikan port 3000 ditutup pada firewall supaya satu-satunya laluan masuk adalah melalui proksi.
Apakah perbezaan antara sandbox tempatan, Docker dan Kubernetes?
local menjalankan kod alat sebagai proses anak bagi runtime pada hos, dengan kebenaran pengguna runtime dan tanpa pengasingan. docker memberikan setiap sesi bekas dan sistem failnya sendiri serta memadamkannya apabila sesi berakhir, dan ia mengehadkan memori serta CPU hanya jika blok resources dalam persekitaran menetapkannya. kubernetes menjalankan sesi sebagai pod dan mengendalikannya dengan kubectl exec, yang memerlukan kubectl di dalam imej runtime dan RBAC pada pod serta sub-sumber exec dalam namespace sasaran. Backend keempat, pekerja yang dihoskan sendiri (self-hosted worker), meletakkan kerja dalam baris gilir untuk pekerja luaran supaya kod dijalankan di luar hos.
Apakah sebenarnya yang perlu saya sandarkan?
Direktori .managed-agents/ dalam ruang kerja. Ia menyimpan config.yaml, pangkalan data SQLite data.db yang mengandungi ejen, sesi, entri peti simpanan kelayakan dan entri memori, serta fail yang dimuat naik, pakej kemahiran dan syot kilas sesi. Hentikan servis sebelum menyalinnya supaya SQLite tidak ditulis semasa arkib sedang dibuat. Kunci API penyedia yang dirujuk sebagai ${OPENAI_API_KEY} tidak berada di dalam sandaran, jadi simpan kunci tersebut secara berasingan.
Mengapa perlu klon tag v0.3.8 dan bukannya main?
Tag ialah pepohon yang tetap, jadi kunci konfigurasi dan arahan CLI yang anda baca adalah yang anda akan peroleh. main berubah-ubah, dan kunci konfigurasi boleh dinamakan semula antara masa panduan ditulis dan masa anda menjalankannya. Projek ini juga memberi amaran bahawa pakej managed-agents yang tidak mempunyai skop pada npm bukanlah projek ini, jadi npx managed-agents akan memasang sesuatu yang tidak berkaitan. Keluaran v0.3.1 wujud terutamanya untuk menggantikan permulaan pantas npm tersebut dengan laluan sumber bertag yang dipinkan.