Autor: Jak samodzielnie uruchomić środowisko SandBase Harness
Instrukcja instalacji SandBase Harness v0.3.2 na własnym serwerze VPS. Skonfiguruj pliki YAML, serwery MCP oraz SDK Anthropic, aby w pełni kontrolować swoje środowisko agenta.
Co zyskujesz, uruchamiając samodzielnie środowisko uruchomieniowe agenta SandBase
Samodzielne uruchomienie środowiska uruchomieniowego agenta SandBase oznacza działanie SandBase Harness na własnym serwerze. Dzięki temu sesje, poświadczenia, pamięć oraz dzienniki audytu znajdują się na Twoim dysku, a nie na infrastrukturze podmiotu zewnętrznego. Jest to usługa Node. Nasłuchuje ona na 127.0.0.1:3000, udostępnia API HTTP /v1 oraz konsolę internetową, a swój stan przechowuje w bazie SQLite obok plików agenta.
API /v1 jest wzorowane na Claude Managed Agents (CMA), czyli hostowanym API zarządzanych agentów. To właśnie czyni to środowisko uruchomieniowe interesującym w obu kierunkach: możesz pisać kod przy użyciu Anthropic SDK i skierować jego baseURL na własną maszynę, a następnie przenieść ten sam kod do wdrożenia hostowanego.
SandBase Harness nie zawiera modelu w pakiecie. Wywołuje on model zewnętrzny. Według stanu na sierpień 2026 r. obsługuje on OpenAI, Anthropic oraz punkty końcowe zgodne z OpenAI, co obejmuje samodzielnie hostowane bramy oraz dostawców takich jak DeepSeek V4. Nadal musisz dostarczyć własny klucz API lub korzystać z lokalnego serwera obsługującego API OpenAI.
Wymagania wstępne
- Serwer VPS z systemem Ubuntu 24.04 i co najmniej 2 GB pamięci RAM. Kompilacja TypeScript jest najbardziej zasobożernym etapem instalacji.
- Node.js w wersji 22 lub nowszej oraz npm w wersji 10 lub nowszej. Są to sztywne wymagania minimalne określone przez projekt.
gitoraz klucz API dla wybranego dostawcy modelu.- Docker, wymagany wyłącznie w przypadku korzystania z izolowanych kontenerów dla sesji.
System Ubuntu 24.04 dostarcza w swoich repozytoriach pakiet Node 18.19, co jest wartością poniżej wymaganego minimum, dlatego należy pobrać Node z NodeSource.
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -vPolecenie node -v powinno zwrócić wynik v22 lub wyższy, a npm -v powinno zwrócić 10 lub wyższy. Jeśli node -v nadal zwraca v18.19.1, oznacza to, że pakiet dystrybucyjny jest nadal zainstalowany i ma pierwszeństwo w PATH. Należy go usunąć przed kontynuowaniem, ponieważ proces budowania korzysta z wersji node wykrytej przez powłokę.
Instalacja SandBase z tagu v0.3.2
Instalację należy przeprowadzać z tagu, nigdy z ruchomej gałęzi (branch). Czyste klonowanie (bare clone) repozytorium main pobiera zmiany wprowadzone w ostatniej godzinie, przez co poniższe klucze konfiguracyjne mogą być z nimi niezgodne. Wersja v0.3.2 jest aktualnym tagiem na dzień 16 sierpnia 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 buildNależy użyć npm ci, a nie npm install. Polecenie ci instaluje dokładne wersje zapisane w zatwierdzonym pliku blokady (lockfile), dzięki czemu drzewo plików jest identyczne z tym, które zostało przetestowane przez twórców. Polecenie npm install pozwala na rozwiązywanie nowszych wersji, co sprawia, że przypięty tag przestaje być w praktyce przypięty.
Teraz należy utworzyć obszar roboczy (workspace). Jest to oddzielny katalog przechowujący pliki agenta oraz cały stan środowiska uruchomieniowego. Przechowywanie go poza katalogiem źródłowym pozwala na pobranie nowszego tagu bez naruszania danych.
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 startPolecenie init tworzy katalog .managed-agents/ wewnątrz obszaru roboczego. Polecenie start uruchamia konsolę pod adresem http://127.0.0.1:3000/dashboard oraz API pod adresem http://127.0.0.1:3000/v1. Żaden z tych adresów nie jest jeszcze dostępny z poziomu laptopa, co jest zachowaniem prawidłowym i zostanie omówione w dalszej części. Na ten moment konsolę można uzyskać poprzez SSH:
ssh -N -L 3000:127.0.0.1:3000 you@your-serverDługa ścieżka node .../dist/index.js jest niepraktyczna, dlatego należy nadać jej nazwę.
alias sandbase='node /opt/sandbase/sandbase-harness/dist/index.js'Poniższe polecenia zostały zapisane z użyciem sandbase <command> w oparciu o to założenie.
Nie instaluj tego z npm
Projekt zaznacza to w swojej dokumentacji instalacji: niezgrupowany pakiet managed-agents widoczny w npm nie należy do tego projektu. Zatem npx managed-agents oraz npm install -g managed-agents pobierają coś niezwiązanego z wymaganym środowiskiem uruchomieniowym. Należy instalować z otagowanego źródła GitHub, dopóki opiekunowie nie ogłoszą oficjalnego pakietu w przestrzeni nazw (scoped package). Nie jest to mało istotna uwaga w historii projektu: wersja v0.3.1 istnieje głównie po to, aby zastąpić stary szybki start z npm ścieżką do przypiętego, otagowanego źródła.
Wskazanie dostawcy modelu dla obszaru roboczego
init zapisuje .managed-agents/config.yaml. Jeden dostawca jest konfigurowany dla całego obszaru roboczego, a poszczególni agenci wybierają następnie konkretne identyfikatory modeli.
model:
provider: openai
api_key: ${OPENAI_API_KEY}
storage:
metadata:
provider: sqlite
options: {}
artifacts:
provider: local
options:
base_path: filesFormularz ${OPENAI_API_KEY} pobiera wartość ze środowiska procesu, dzięki czemu klucz nie trafia do pliku konfiguracyjnego ani do żadnej kopii zapasowej tego pliku. Należy umieścić go w pliku środowiskowym, który może odczytać tylko root, ponieważ systemd odczytuje EnvironmentFile= jako root przed obniżeniem uprawnień.
sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.envOtwórz ten plik w edytorze i dodaj jedną linię, OPENAI_API_KEY=sk-.... Tutaj należy umieszczać klucze dostawców. Sekrety, których agent używa podczas sesji, powinny trafiać do magazynów poświadczeń środowiska uruchomieniowego; jest to inny problem o innym zasięgu potencjalnych szkód, a lektura utrzymywanie sekretów poza agentami AI jest zalecana przed wklejeniem produkcyjnego tokena w którekolwiek z tych miejsc.
Plik YAML agenta: mcp_servers, narzędzia i polityki uprawnień
Agenci są definiowani jako pliki YAML w katalogu agents/ obszaru roboczego. Jest to część środowiska uruchomieniowego, w której spędzisz najwięcej czasu. Znaczenie kluczy staje się bardziej zrozumiałe po ręcznym napisaniu prostej pętli agenta, ponieważ każdy z nich odpowiada za element, który w przeciwnym razie musiałbyś zaprogramować samodzielnie: prompt systemowy, listę narzędzi oraz weryfikację uruchamianą przed wywołaniem narzędzia.
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-commanderZaładuj go i sprawdź, czy został poprawnie wczytany:
sandbase reload
sandbase list
sandbase chat agent_assistant --message "hello"reload importuje bazowy plik YAML do SQLite. list powinno teraz wyświetlić agenta wraz z jego identyfikatorem. Jeśli list go nie pokazuje, oznacza to, że plik nie został sparsowany, a przyczyna tego stanu znajduje się w .managed-agents/logs/runtime.log.
mcp_servers definiuje punkty końcowe MCP (model context protocol). type: url oznacza, że środowisko wykonawcze komunikuje się przez HTTP z serwerem działającym w innym miejscu, więc można tu wykorzystać wszystko, co już działa, w tym serwery MCP hostowane na tym samym VPS co środowisko wykonawcze. Wyszukiwanie w sieci jest zwykle pierwszym narzędziem, po które sięga się w takiej sytuacji. Przed jego skonfigurowaniem warto przeczytać jak przekazać agentowi własną instancję SearXNG, ponieważ narzędzie zwracające strony napisane przez nieznane osoby umieszcza niezaufany tekst bezpośrednio w kontekście modelu. Bezpieczniejszy pierwszy krok ma odwrotną strukturę: jest nim punkt końcowy tylko do odczytu, udostępniający dane, które już są pod kontrolą użytkownika. Tak działa openGym udostępniający dane obok samego trackera treningów. Dzięki temu agent może odpowiadać na pytania dotyczące historii treningów, ale nie może jej modyfikować.
Sama deklaracja serwera nie udostępnia jego narzędzi agentowi. Służy do tego lista tools poprzez wpis mcp_toolset, którego mcp_server_name musi być zgodne z name zdefiniowanym powyżej. Jeśli agent zachowuje się tak, jakby narzędzia MCP nie istniały, porównaj te dwa ciągi znak po znaku, zanim zaczniesz szukać przyczyny gdziekolwiek indziej.
agent_toolset_20260401 to wbudowany zestaw narzędzi. Sufiks z datą to wersja schematu, dzięki czemu agent przypisany do tej wersji zachowuje definicje narzędzi, dla których został stworzony. default_config ustala politykę dla każdego narzędzia w zestawie, a każdy wpis w sekcji configs nadpisuje ustawienia konkretnego narzędzia według nazwy, tak jak bash w przykładzie.
permission_policy to miejsce, w którym środowisko uruchomieniowe zyskuje przewagę nad zwykłym wywołaniem modelu. always_ask wstrzymuje sesję i oczekuje na zatwierdzenie wywołania przez człowieka przed jego wykonaniem. always_allow pozwala na jego przepuszczenie. Ustawienie bash na always_ask oznacza, że agent nie może uruchomić polecenia powłoki bez Twojego wcześniejszego wglądu w dokładną treść komendy; jest to ta sama kontrola, którą stosuje się przy bezpiecznym uruchamianiu Claude Code na VPS. Jeśli używasz również DeepSeek Harness, te same mechanizmy kontrolne są tam dostępne jako dodatki, a nie klucze YAML, przy czym wtyczki ograniczające budżet i kontrolujące wywołania narzędzi są najbliższym odpowiednikiem tego bloku.
Trzy tryby piaskownicy i zastosowanie każdego z nich
Wywołania narzędzi wykonujące kod działają wewnątrz piaskownicy. Backend wybiera się dla każdego środowiska poprzez sandbox_provider w obiekcie config środowiska lub w konsoli w sekcji Settings, a następnie Sandbox. Środowiska tworzy się przez API pod adresem POST /v1/environments.
local uruchamia kod jako proces potomny środowiska wykonawczego, na hoście, z uprawnieniami użytkownika tego środowiska. Jest to tryb domyślny i jest on akceptowalny, gdy jesteś jedynym użytkownikiem, a agent jedynie odczytuje pliki, których jesteś właścicielem. Nie zapewnia on izolacji. Wywołanie narzędzia usuwające pliki usunie Twoje pliki, a wywołanie odczytujące /etc/sandbase/runtime.env odczyta Twój klucz dostawcy.
docker uruchamia jeden kontener na sesję.
{
"sandbox_provider": "docker",
"image": "node:22-slim",
"resources": { "memory": "1g", "cpu": 1 }
}Sesja otrzymuje własny system plików, własny limit pamięci oraz własny przydział CPU, a kontener jest usuwany wraz z sesją. Przełącz się na ten tryb w momencie, gdy agent uruchamia kod, którego nie napisałeś. Kosztem jest konieczność posiadania przez użytkownika środowiska wykonawczego dostępu do gniazda Docker, a przynależność do grupy docker jest równoważna z uprawnieniami root na hoście. Kontenery per-sesja mają taką samą strukturę jak samodzielnie hostowane piaskownice agenta z jednym kontenerem na uruchomienie, więc argumentacja dotycząca tego, do czego może uzyskać dostęp proces po ucieczce z kontenera, ma tu pełne zastosowanie.
kubernetes uruchamia obciążenie sesji jako pod i steruje nim za pomocą kubectl exec oraz kubectl cp. Obraz środowiska wykonawczego musi zawierać kubectl, a jego ServiceAccount musi posiadać uprawnienia RBAC (role-based access control) do tworzenia, usuwania, pobierania, listowania i obserwowania podów w docelowej przestrzeni nazw, a także dostęp do podzasobu exec. Ten tryb jest wart konfiguracji tylko wtedy, gdy już zarządzasz klastrem.
Dlaczego środowisko uruchomieniowe jest powiązane z 127.0.0.1?
Ponieważ uruchamia się ono z wyłączonym uwierzytelnianiem. Środowisko uruchomieniowe włącza uwierzytelnianie za pomocą tokenów bearer, gdy istnieje co najmniej jeden klucz API, a świeża instalacja init nie tworzy żadnego. Powiązanie z 0.0.0.0 przy ustawieniach domyślnych wystawiłoby nieuwierzytelnione środowisko uruchomieniowe agenta, posiadające narzędzia powłoki i klucz dostawcy, na publiczny dostęp w Internecie.
Jeśli chcesz, aby usługa była dostępna zdalnie, pozostaw adres powiązania bez zmian i wykonaj dwie inne czynności.
Po pierwsze, włącz uwierzytelnianie. Ustaw MANAGED_AGENTS_API_KEY w pliku środowiskowym usługi lub utwórz klucz za pomocą POST /v1/api-keys, co spowoduje jednorazowe wyświetlenie pola secret_key, które nie będzie już później dostępne. Klienci muszą następnie przesyłać Authorization: Bearer <key> w każdym żądaniu. Jeden klucz oznacza jedną współdzieloną tożsamość, więc jeśli potrzebujesz oddzielnego, odizolowanego agenta dla każdego członka zespołu z kluczami dostawcy przechowywanymi w jednej bramie, OneCLI jest zaprojektowany do tego modelu.
Po drugie, umieść przed usługą reverse proxy i przeprowadź tam terminację TLS (transport layer security). Środowisko uruchomieniowe z założenia obsługuje zwykły protokół HTTP i oczekuje, że certyfikaty zostaną obsłużone przez inny komponent.
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;
}
}Dwie z tych linii nie są tylko dekoracją. proxy_buffering off jest istotne, ponieważ sesje są przesyłane strumieniowo za pomocą server-sent events (SSE), a przy włączonym buforowaniu nginx wstrzymuje odpowiedź do momentu zapełnienia bufora, przez co konsola nie wyświetla nic podczas pracy agenta, a następnie wyrzuca całą zawartość na końcu. proxy_read_timeout 3600s jest istotne, ponieważ wartość domyślna wynosi 60 sekund, więc strumień, w którym przez ponad minutę nie ma aktywności, jest zamykany przez proxy w trakcie trwania operacji, co wygląda jak awaria środowiska uruchomieniowego.
Na firewallu otwórz porty 22 oraz 443. Pozostaw port 3000 zamknięty, ponieważ proxy uzyskuje do niego dostęp przez loopback i żaden zewnętrzny podmiot nie powinien mieć takiej możliwości.
Skierowanie Anthropic SDK na własny serwer
Środowisko uruchomieniowe implementuje interfejs w formacie CMA /v1, dzięki czemu klient Anthropic SDK komunikuje się z nim po zmianie jednego pola.
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'
});Akceptowane są również nagłówki w wersji beta, które wysyłają klienci Claude Managed Agents, anthropic-beta: managed-agents-2026-04-01 oraz anthropic-beta: agent-memory-2026-07-22. W przypadku lokalnego środowiska uruchomieniowego są one opcjonalne. Istnieją one po to, aby kod napisany dla wdrożenia hostowanego działał tutaj bez zmian.
Zgodność jest wysoka, ale nie całkowita. Przed założeniem, że dany interfejs istnieje, należy przeczytać docs/api-matrix.md w pobranym repozytorium, ponieważ projekt dokumentuje tam własne braki, w tym niestandardowe narzędzia po stronie klienta, które nadal wymagają rejestracji nazw wykraczającej poza obecny protokół zdarzeń i wyników.
Zwykły protokół HTTP działa równie dobrze i jest najszybszym sposobem na sprawdzenie, czy środowisko uruchomieniowe działa:
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}'Prawidłowa odpowiedź to strumień zdarzeń, który jest stale przesyłany. Jeśli połączenie zostanie przerwane, należy wznowić pracę od ostatniego odebranego zdarzenia zamiast powtarzać całą turę:
curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
-H "Last-Event-ID: EVENT_ID"Ten wznawialny strumień jest powodem, dla którego sesja przetrwa zamknięcie laptopa. Zdarzenia są utrwalane na serwerze, więc klient odtwarza dziennik, zamiast przechowywać jedyną kopię danych.
Gdzie na dysku przechowywane są poświadczenia, pamięć i ścieżki audytu
Wszystkie zasoby środowiska uruchomieniowego znajdują się w katalogu .managed-agents/ w obszarze roboczym.
.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/data.dbzawiera metadane SQLite: agentów, sesje, wpisy w skarbcu poświadczeń, wpisy w pamięci oraz klucze API.files/przechowuje bajty przesłanych plików, askills/przechowuje przesłane pakiety umiejętności.snapshots/przechowuje migawki obszarów roboczych sesji, asandbox/zawiera katalogi robocze sesji działających w trybie lokalnym.logs/runtime.logto pierwsze miejsce, które należy sprawdzić, gdy proces nie wykazuje żadnej aktywności.
Skarbce poświadczeń to grupy sekretów, z których każdy dodawany jest za pomocą auth_type, takiego jak environment_variable, i przypisywany do sesji poprzez vault_ids w momencie jej tworzenia. Pamięci przechowują nazwane wpisy, które montuje się w sesji jako memory_store z własnymi ustawieniami dostępu i instrukcjami. Oba elementy znajdują się w data.db, co stanowi kluczową różnicę między tym rozwiązaniem a zwykłym wywołaniem modelu: środowisko uruchomieniowe zapamiętuje dane pomiędzy sesjami i zapisuje przebieg zdarzeń.
Ponieważ całość znajduje się w jednym katalogu, należy tworzyć jego kopię zapasową jako jedną całość.
sudo systemctl stop sandbase
sudo tar czf /root/sandbase-$(date +%F).tgz -C /opt/sandbase/workspace .managed-agents
sudo systemctl start sandbaseNajpierw należy zatrzymać usługę. Kopiowanie bazy danych SQLite w trakcie zapisu przez środowisko uruchomieniowe może doprowadzić do powstania pliku, którego nie da się otworzyć podczas przywracania, co zostanie wykryte dopiero w momencie wystąpienia awarii. Jeśli preferowane jest przechowywanie plików YAML agentów w git, a stanu w innej lokalizacji, dokumentacja wdrożeniowa pozwala na wskazanie lokalizacji stanu za pomocą --data-dir w start.
Przywracanie przebiega w odwrotnej kolejności: należy pobrać ten sam tag na nowym serwerze, rozpakować archiwum do obszaru roboczego i uruchomić usługę. Klucz dostawcy nie znajduje się w archiwum, jeśli użyto formy ${OPENAI_API_KEY}, dlatego należy przechowywać go w bezpiecznym miejscu.
Uruchomienie w systemd
Należy przypisać procesowi dedykowanego użytkownika, aby wywołanie narzędzia w trybie lokalnego piaskownicy (sandbox) nie mogło działać w imieniu użytkownika głównego.
sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbaseZapisz plik jako /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.targetPrzykładowe wdrożenie projektu odwołuje się do pliku binarnego managed-agents w lokalizacji PATH. Instalacja z otagowanego źródła nie tworzy tego pliku, dlatego ExecStart uruchamia node bezpośrednio dla zbudowanego punktu wejścia.
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/dashboardPrawidłowy wynik to active (running) z status oraz 200 z curl. W przypadku innego wyniku należy najpierw przeczytać journalctl -u sandbase -n 50, a następnie .managed-agents/logs/runtime.log. Kluczowe znaczenie ma enable --now, ponieważ proces uruchomiony ręcznie zostanie zakończony po kolejnym restarcie systemu.
Co ulega awarii i jaki komunikat zobaczysz
npm run build zostaje zamknięty bez błędu ze strony npm. Na serwerze VPS z 1 GB pamięci RAM kompilacja TypeScript jest przerywana przez mechanizm OOM (out-of-memory) jądra systemu, który raportuje ten fakt do dziennika jądra, a nie do npm. Potwierdź to za pomocą journalctl -k | grep -i "out of memory", co wyświetli linię wskazującą na zamknięty proces node. Dodaj przestrzeń wymiany (swap) lub przeprowadź budowanie na większej instancji i skopiuj dist/.
Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. Inny proces już zajmuje ten port. sudo ss -lntp | grep 3000 wskaże ten proces. Należy go zatrzymać lub uruchomić środowisko wykonawcze z --port 3001 i zaktualizować proxy.
Panel sterowania nie ładuje się z Twojego laptopa. Jest to zamierzone zachowanie, ponieważ środowisko wykonawcze wiąże się z interfejsem loopback. Użyj tunelu SSH opisanego powyżej lub dokończ konfigurację reverse proxy. Nie naprawiaj tego za pomocą --host 0.0.0.0, ponieważ uwierzytelnianie jest wyłączone, dopóki nie istnieje klucz.
Piaskownice Docker kończą się błędem permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock. Użytkownik sandbase nie należy do grupy docker. Napraw to za pomocą sudo usermod -aG docker sandbase i zrestartuj usługę. Zrozum, co właśnie przyznałeś: ta grupa ma uprawnienia root na hoście, co niweluje część korzyści z przypisania środowisku wykonawczemu własnego użytkownika.
Piaskownice Kubernetes kończą się błędem Error from server (Forbidden). Konto ServiceAccount nie posiada uprawnień do podów lub podzasobu exec. Sprawdź to bezpośrednio za pomocą kubectl auth can-i create pods/exec -n <namespace>, co zwróci yes lub no.
Każde żądanie zwraca 401 po dodaniu klucza API. Uwierzytelnianie włącza się w momencie utworzenia pierwszego klucza i dotyczy zarówno konsoli, jak i API. Wyślij Authorization: Bearer <key>. Jeśli zgubiłeś klucz, utwórz nowy, ponieważ secret_key jest zwracany tylko raz i nie jest przechowywany w czytelnej formie.
Narzędzia serwera MCP nie pojawiają się w sesji. Sprawdź mcp_server_name w bloku tools w odniesieniu do name w mcp_servers, a następnie sprawdź, czy środowisko wykonawcze może połączyć się z tym adresem URL bezpośrednio z serwera za pomocą curl -i <url>. Serwer MCP typu URL jest zależnością sieciową, a serwer VPS rozwiązuje nazwy i kieruje ruch inaczej niż Twój laptop.
FAQ
Czy mogę uruchomić SandBase Harness bez klucza OpenAI lub Anthropic?
Tak, jeśli posiadasz endpoint kompatybilny z OpenAI. Środowisko uruchomieniowe wspiera dostawców OpenAI, Anthropic oraz dostawców zgodnych z API OpenAI, więc lokalny serwer obsługujący API OpenAI będzie działał. Ustaw dostawcę obszaru roboczego w .managed-agents/config.yaml i wskaż na niego w api_key oraz w polu endpoint. Środowisko uruchomieniowe nie zawiera własnego modelu, więc konieczne jest zapewnienie zewnętrznego źródła odpowiedzi na zapytania.
Czy wystawienie środowiska uruchomieniowego na publicznym porcie jest bezpieczne?
W domyślnej konfiguracji nie. Usługa wiąże się z 127.0.0.1:3000 i uruchamia bez włączonego uwierzytelniania, a rozwiązaniem nie jest zmiana adresu wiązania. Utwórz klucz API lub ustaw MANAGED_AGENTS_API_KEY, aby włączyć uwierzytelnianie za pomocą bearer-token. Następnie umieść nginx lub Caddy przed usługą w celu obsługi TLS i zablokuj port 3000 na firewallu, tak aby jedyna droga dostępu prowadziła przez proxy.
Jaka jest różnica między piaskownicami lokalnymi, Docker oraz Kubernetes?
local uruchamia kod narzędziowy jako proces potomny środowiska uruchomieniowego na hoście, z uprawnieniami użytkownika uruchamiającego i bez izolacji. docker przydziela każdej sesji osobny kontener z własnym systemem plików, limitami pamięci i przydziałem CPU, usuwając go po zakończeniu sesji. kubernetes uruchamia sesję jako pod i zarządza nią za pomocą kubectl exec, co wymaga kubectl wewnątrz obrazu środowiska uruchomieniowego oraz odpowiednich uprawnień RBAC dla podów, a także zasobu podrzędnego exec w docelowej przestrzeni nazw.
Co dokładnie muszę archiwizować w ramach kopii zapasowej?
Katalog .managed-agents/ w obszarze roboczym. Przechowuje on config.yaml, bazę danych SQLite data.db zawierającą agentów, sesje, wpisy w skarbcu poświadczeń i pamięci, a także przesłane pliki, pakiety umiejętności i migawki sesji. Przed kopiowaniem zatrzymaj usługę, aby uniknąć zapisu do bazy SQLite w trakcie tworzenia archiwum. Klucze API dostawców, do których odwołuje się ${OPENAI_API_KEY}, nie znajdują się w kopii zapasowej, więc należy przechowywać je oddzielnie.
Dlaczego należy klonować tag v0.3.2 zamiast gałęzi main?
Tag stanowi stały stan drzewa plików, dzięki czemu klucze konfiguracyjne i polecenia CLI opisane w dokumentacji są zgodne z otrzymaną wersją. main ulega zmianom, a klucze konfiguracyjne mogą zostać przemianowane w czasie między napisaniem poradnika a jego wykonaniem. Projekt ostrzega również, że pakiet managed-agents w rejestrze npm nie jest powiązany z tym projektem, więc npx managed-agents instaluje niepowiązane oprogramowanie. Wydanie v0.3.1 istnieje głównie po to, aby zastąpić szybki start z npm ścieżką do przypiętego źródła oznaczonego tagiem.