Autor: Matt Connor 2026-08-16

Jak samodzielnie uruchomić SandBase agent runtime

Q: 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, aby jedyna droga dostępu prowadziła przez proxy.

Q: 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 udziałem procesora, 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 uprawnień RBAC dla podów, a także zasobu podrzędnego exec w docelowej przestrzeni nazw.

Q: Co dokładnie należy archiwizować w ramach kopii zapasowej?

Katalog .managed-agents/ w obszarze roboczym. Przechowuje on config.yaml, bazę danych data.db w formacie SQLite 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.

Instrukcja instalacji SandBase Harness v0.3.2 na własnym serwerze VPS. Konfiguracja agenta YAML, serwerów MCP, trybów sandbox oraz przekierowanie Anthropic SDK na lokalny host.

Co zyskujesz, uruchamiając samodzielnie środowisko uruchomieniowe agenta SandBase

Samodzielne uruchomienie środowiska uruchomieniowe 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 napisać 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 zestawie. Wywołuje on model zewnętrzny. Według stanu na sierpień 2026 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 22 lub nowszy oraz npm 10 lub nowszy. Są to sztywne wymagania minimalne określone przez projekt.
git oraz klucz API dla wybranego dostawcy modelu.
Docker, wymagany wyłącznie w przypadku korzystania z izolowanych kontenerów dla poszczególnych sesji.

Ubuntu 24.04 dostarcza w swoich repozytoriach Node 18.19, co jest wersją poniżej wymaganego minimum, dlatego należy zainstalować Node z 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 powinno zwrócić v22 lub wyższą wersję, a npm -v powinno zwrócić 10 lub wyższą wersję. 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 tego node, który zostanie znaleziony w powłoce jako pierwszy.

Instalacja SandBase z tagu v0.3.2

Instalację należy przeprowadzać z tagu, nigdy z ruchomej gałęzi (branch). Czyste klonowanie (bare clone) main pobiera kod, który pojawił się godzinę temu, a poniższe klucze konfiguracyjne mogą być z nim niezgodne. v0.3.2 to aktualny tag 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 build

Należy używać npm ci, a nie npm install. ci instaluje dokładne wersje zapisane w zatwierdzonym pliku blokady (lockfile), dzięki czemu drzewo plików jest identyczne z tym, które przetestowali twórcy. npm install pozwala na rozwiązywanie nowszych wersji, co sprawia, że przypięty tag przestaje być stabilny.

Teraz należy utworzyć obszar roboczy (workspace). Obszar roboczy to oddzielny katalog, który przechowuje 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 start

init tworzy katalog .managed-agents/ wewnątrz obszaru roboczego. 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 nich nie jest jeszcze dostępny z poziomu laptopa, co jest zachowaniem prawidłowym i zostanie omówione w dalszej części. Na razie należy uzyskać dostęp do konsoli przez SSH:

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

Długa ścieżka node .../dist/index.js jest uciążliwa, dlatego warto nadać jej nazwę.

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

Poniższe polecenia zostały zapisane jako sandbase <command> w oparciu o to założenie.

Nie instaluj pakietu z npm

Dokumentacja instalacyjna projektu zawiera następujące ostrzeżenie: pakiet managed-agents dostępny w rejestrze npm nie jest tym projektem. W związku z tym polecenia npx managed-agents oraz npm install -g managed-agents pobierają oprogramowanie niezwiązane z oczekiwanym środowiskiem uruchomieniowym. Instalację należy przeprowadzić bezpośrednio z otagowanego źródła w serwisie GitHub, dopóki opiekunowie projektu nie opublikują oficjalnego pakietu w przestrzeni nazw (scoped package). Nie jest to mało istotna uwaga w historii projektu: wersja v0.3.1 powstała głównie w celu zastąpienia starej metody szybkiego startu z npm ścieżką wskazującą na przypięte, otagowane źródło.

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: files

Formularz ${OPENAI_API_KEY} pobiera wartość ze środowiska procesu, dzięki czemu klucz nie znajduje się w pliku konfiguracyjnym ani w żadnej jego kopii zapasowej. 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.env

Otwórz ten plik w edytorze i dodaj jedną linię, OPENAI_API_KEY=sk-.... Klucze dostawców powinny znajdować się w tym miejscu. Dane uwierzytelniające, których agent używa podczas sesji, powinny natomiast trafiać do przeznaczonych do tego magazynów w środowisku uruchomieniowym. Jest to odrębne zagadnienie o innym zasięgu potencjalnych szkód, dlatego przed wklejeniem produkcyjnego tokena w którekolwiek z tych miejsc warto zapoznać się z artykułem utrzymywanie sekretów poza agentami AI.

Agent w formacie YAML: 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 użytkownik spędza najwięcej czasu.

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

Załaduj go i sprawdź, czy został poprawnie zarejestrowany:

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ł przetworzony, a przyczyna tego stanu znajduje się w .managed-agents/logs/runtime.log.

mcp_servers deklaruje punkty końcowe MCP (model context protocol). type: url oznacza, że środowisko uruchomieniowe komunikuje się przez HTTP z serwerem działającym w innej lokalizacji, więc każde rozwiązanie już przez Ciebie obsługiwane będzie tutaj działać, w tym serwery MCP hostowane na tym samym VPS co środowisko uruchomieniowe.

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 odpowiada wartości name zdefiniowanej 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 wcześniejszego wyświetlenia dokładnej komendy użytkownikowi; jest to ten sam poziom kontroli, który stosuje się podczas bezpiecznego uruchamiania Claude Code na VPS.

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ę za pomocą API pod adresem POST /v1/environments.

local uruchamia kod jako proces potomny środowiska uruchomieniowego, na hoście, z uprawnieniami użytkownika tego środowiska. Jest to tryb domyślny, odpowiedni w sytuacji, gdy użytkownik jest jedyny, a agent jedynie odczytuje pliki należące do niego. Nie zapewnia on izolacji. Wywołanie narzędzia usuwające pliki usunie pliki użytkownika, a wywołanie odczytujące /etc/sandbase/runtime.env odczyta 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, limit pamięci oraz przydział CPU, a kontener jest usuwany wraz z sesją. Na ten tryb należy przełączyć się w momencie, gdy agent uruchamia kod, którego nie napisałeś. Kosztem jest konieczność zapewnienia użytkownikowi środowiska uruchomieniowego dostępu do gniazda Docker, a członkostwo w grupie docker jest równoważne 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 zasięgu ucieczki procesu pozostaje tutaj niezmieniona.

kubernetes uruchamia obciążenie sesji jako pod i steruje nim za pomocą kubectl exec oraz kubectl cp. Obraz środowiska uruchomieniowego wymaga obecności 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 klaster jest już utrzymywany.

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-token), 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 usługa ma być dostępna zdalnie, należy pozostawić adres powiązania bez zmian i wykonać 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.

Po drugie, umieść przed usługą odwrotne proxy i przeprowadź tam terminację TLS (transport layer security). Środowisko uruchomieniowe z założenia obsługuje zwykłe HTTP i oczekuje, że certyfikatami zajmie się 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; w rezultacie konsola nie wyświetla nic podczas pracy agenta, a następnie zrzuca całą treść 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, zostaje zamknięty przez proxy w trakcie trwania operacji, co wygląda jak awaria środowiska uruchomieniowego.

Na zaporze sieciowej 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 kształcie 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'
});

Akceptuje ono również nagłówki beta wysyłane przez klientów Claude Managed Agents, anthropic-beta: managed-agents-2026-04-01 oraz anthropic-beta: agent-memory-2026-07-22. Są one opcjonalne w przypadku lokalnego środowiska uruchomieniowego. Istnieją 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 powyżej bieżącego protokołu 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 napływa w sposób ciągły. Jeśli połączenie zostanie przerwane, należy wznowić pracę od ostatniego zarejestrowanego 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 ślady audytu

Wszystkie zasoby środowiska uruchomieniowego znajdują się w katalogu .managed-agents/ wewnątrz obszaru roboczego.

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

data.db zawiera metadane SQLite: agentów, sesje, wpisy w skarbcu poświadczeń, wpisy w pamięci oraz klucze API.
files/ przechowuje bajty przesłanych plików, a skills/ przechowuje przesłane pakiety umiejętności.
snapshots/ przechowuje migawki obszarów roboczych sesji, a sandbox/ zawiera katalogi robocze sesji działających w trybie lokalnym.
logs/runtime.log to pierwsze miejsce, które należy sprawdzić, gdy usługa 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 przez 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 bezpośrednim wywołaniem modelu: środowisko uruchomieniowe zapamiętuje stan między sesjami i zapisuje przebieg zdarzeń.

Ponieważ jest to jeden katalog, należy wykonywać jego kopię zapasową jako całość.

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

Najpierw zatrzymaj usługę. Kopiowanie bazy danych SQLite w trakcie zapisu przez środowisko uruchomieniowe może doprowadzić do powstania pliku, którego nie uda się otworzyć podczas przywracania – co zostanie wykryte dopiero w momencie, gdy będzie on potrzebny. Jeśli wolisz przechowywać pliki YAML agentów w git, a stan w innym miejscu, dokumentacja wdrożeniowa pozwala na wskazanie lokalizacji stanu za pomocą --data-dir w start.

Przywracanie przebiega odwrotnie: pobierz tę samą wersję (tag) na nowym serwerze, rozpakuj archiwum do obszaru roboczego i uruchom usługę. Klucz dostawcy nie znajduje się w archiwum, jeśli użyto metody ${OPENAI_API_KEY}, dlatego należy przechowywać go w bezpiecznym miejscu.

Uruchamianie za pomocą systemd

Należy przypisać środowisko uruchomieniowe do dedykowanego użytkownika, aby wywołanie narzędzia w trybie lokalnej piaskownicy 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/sandbase

Zapisz 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.target

Przykładowa konfiguracja wdrożeniowa projektu wywołuje plik binarny managed-agents w lokalizacji PATH. Instalacja z otagowanego źródła nie tworzy tego pliku, dlatego ExecStart uruchamia node bezpośrednio względem 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/dashboard

Prawidł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 następnym 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 systemowego, a nie do npm. Potwierdź to za pomocą journalctl -k | grep -i "out of memory", co wyświetli wiersz wskazujący 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ć konfigurację proxy.

Panel sterowania nie ładuje się z 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 do czasu utworzenia klucza.

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 konsekwencje tego działania: ta grupa posiada uprawnienia root na hoście, co częściowo niweluje 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 istnienia pierwszego klucza i dotyczy zarówno konsoli, jak i API. Wyślij Authorization: Bearer <key>. Jeśli klucz został utracony, utwórz nowy, ponieważ secret_key jest zwracane tylko raz i nie jest przechowywane 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 zweryfikuj, 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 stanowi zależność sieciową, a serwer VPS inaczej rozwiązuje nazwy i kieruje ruch niż laptop.

FAQ

Czy można uruchomić SandBase Harness bez klucza OpenAI lub Anthropic?

Tak, jeśli dysponujesz endpointem zgodnym z OpenAI. Środowisko uruchomieniowe obsługuje dostawców OpenAI, Anthropic oraz dostawców kompatybilnych z OpenAI, więc lokalny serwer obsługujący API OpenAI będzie działał. Ustaw dostawcę obszaru roboczego w .managed-agents/config.yaml i skieruj na niego api_key oraz endpoint. Środowisko uruchomieniowe nie zawiera własnego modelu, więc konieczne jest zapewnienie usługi odpowiadającej 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, 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 udziałem procesora, 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 uprawnień RBAC dla podów, a także zasobu podrzędnego exec w docelowej przestrzeni nazw.

Co dokładnie należy archiwizować w ramach kopii zapasowej?

Katalog .managed-agents/ w obszarze roboczym. Przechowuje on config.yaml, bazę danych data.db w formacie SQLite 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 niezmienną wersję drzewa plików, dzięki czemu klucze konfiguracyjne i polecenia CLI opisane w dokumentacji są zgodne z otrzymanym kodem. main ulega zmianom, a klucze konfiguracyjne mogą zostać przemianowane w czasie między publikacją 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 zainstaluje 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.

#ai-agents #mcp #self-hosting #sandboxing#anthropic-sdk