SandBase Harness v0.3.2 selbst hosten

Was Sie erhalten, wenn Sie die SandBase-Agent-Laufzeit selbst hosten

Self-Hosting der SandBase-Agent-Laufzeit bedeutet, SandBase Harness auf einem eigenen Server zu betreiben. Sitzungen, Zugangsdaten, Arbeitsspeicher und Audit-Trails liegen dadurch auf Ihrer Festplatte statt auf der eines anderen Anbieters. Es handelt sich um einen Node-Dienst. Er lauscht auf 127.0.0.1:3000, stellt eine /v1-HTTP-API und eine Webkonsole bereit und speichert seinen Zustand in SQLite neben Ihren Agent-Dateien.

Die /v1-API ist an Claude Managed Agents (CMA), die gehostete API für verwaltete Agenten, angelehnt. Dadurch ist diese Laufzeit in beide Richtungen interessant: Sie können Code mit dem Anthropic SDK schreiben und dessen baseURL auf Ihren eigenen Server zeigen lassen. Später können Sie denselben Code auf eine gehostete Bereitstellung umstellen.

SandBase Harness enthält kein Modell. Es ruft ein Modell auf. Stand August 2026 unterstützt es OpenAI-, Anthropic- und OpenAI-kompatible Endpunkte. Damit werden selbst gehostete Gateways und Anbieter wie DeepSeek V4 abgedeckt. Sie benötigen weiterhin einen API-Schlüssel oder einen lokalen Server, der die OpenAI API bereitstellt.

Was Sie vor dem Start benötigen

• Einen VPS mit Ubuntu 24.04 und mindestens 2 GB RAM. Der TypeScript-Build ist der aufwendigste Installationsschritt.
• Node.js 22 oder neuer sowie npm 10 oder neuer. Das Projekt nennt beide Versionen als feste Mindestanforderungen.
• git sowie einen API-Schlüssel für den von Ihnen verwendeten Modellanbieter.
• Docker, aber nur, wenn Sie Container-Sandboxes pro Sitzung verwenden möchten.

Ubuntu 24.04 stellt im eigenen Repository Node 18.19 bereit. Diese Version liegt unter der Mindestanforderung. Installieren Sie Node daher stattdessen über 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 sollte v22 oder höher ausgeben, und npm -v sollte 10 oder höher ausgeben. Wenn node -v weiterhin v18.19.1 ausgibt, ist das Distributionspaket noch installiert und hat bei PATH Vorrang. Entfernen Sie es, bevor Sie fortfahren, da der Build die Version von node verwendet, die die Shell findet.

SandBase aus dem v0.3.2-Tag installieren

Installieren Sie immer aus einem Tag, niemals aus einem sich ändernden Branch. Ein Bare-Clone von main enthält den Stand, der möglicherweise erst vor einer Stunde hinzugefügt wurde. Die folgenden Konfigurationsschlüssel passen dann möglicherweise nicht dazu. v0.3.2 ist der aktuelle Tag mit Stand vom 16. August 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

Verwenden Sie npm ci, nicht npm install. ci installiert genau die im versionierten Lockfile festgehaltenen Versionen. Dadurch entspricht Ihr Arbeitsbaum dem von den Maintainer getesteten Arbeitsbaum. npm install darf neuere Versionen auflösen. Dadurch kann ein gepinnter Tag unbemerkt nicht mehr gepinnt sein.

Erstellen Sie jetzt einen Workspace. Der Workspace ist ein separates Verzeichnis für Ihre Agent-Dateien und den gesamten Laufzeitstatus. Wenn er außerhalb des Source-Checkouts liegt, können Sie einen neueren Tag abrufen, ohne Ihre Daten zu verändern.

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 legt im Workspace ein Verzeichnis .managed-agents/ an. start startet die Konsole unter http://127.0.0.1:3000/dashboard und die API unter http://127.0.0.1:3000/v1. Beide sind von Ihrem Laptop aus noch nicht erreichbar. Das ist korrekt und wird weiter unten behandelt. Greifen Sie zunächst per SSH auf die Konsole zu:

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

Der lange Pfad node .../dist/index.js ist umständlich. Geben Sie ihm daher einen Namen.

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

Die folgenden Befehle verwenden auf dieser Grundlage sandbase <command>.

Nicht über npm installieren

Das Projekt weist in seiner eigenen Installationsdokumentation darauf hin: Das auf npm sichtbare nicht durch einen Scope qualifizierte managed-agents-Paket gehört nicht zu diesem Projekt. npx managed-agents und npm install -g managed-agents laden daher etwas, das mit der gewünschten Laufzeit nichts zu tun hat. Installieren Sie das Projekt aus dem getaggten GitHub-Quellcode, bis die Maintainer ein offizielles Paket mit Scope ankündigen. Das ist keine nebensächliche Fußnote in der Projektgeschichte: v0.3.1 dient hauptsächlich dazu, den alten npm-Schnellstart durch den festgelegten Pfad über den getaggten Quellcode zu ersetzen.

Provider für den Workspace festlegen

init schreibt .managed-agents/config.yaml. Für den gesamten Workspace wird ein Provider konfiguriert. Die einzelnen Agents wählen anschließend konkrete Modell-IDs.

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

Das Formular ${OPENAI_API_KEY} übernimmt den Wert aus der Prozessumgebung. Dadurch bleibt der Schlüssel außerhalb der Konfigurationsdatei und außerhalb jedes Backups dieser Datei. Legen Sie ihn in einer Umgebungsdatei ab, die nur root lesen kann, da systemd EnvironmentFile= als root einliest, bevor die Berechtigungen reduziert werden.

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

Öffnen Sie diese Datei in einem Editor und fügen Sie eine Zeile mit OPENAI_API_KEY=sk-... hinzu. Provider-Schlüssel gehören hierhin. Geheimnisse, die ein Agent während einer Sitzung verwendet, gehören dagegen in die Credential-Vaults der Laufzeit. Das ist ein anderes Problem mit einem anderen Schadensradius. Der Abschnitt Geheimnisse von AI-Agents fernhalten ist lesenswert, bevor Sie ein Produktions-Token an eine der beiden Stellen kopieren.

Die Agent-YAML-Datei: mcp_servers, tools und Berechtigungsrichtlinien

Agents werden als YAML-Dateien im Workspace-Verzeichnis agents/ definiert. In diesem Bereich werden Sie während der Laufzeit tatsächlich die meiste Zeit arbeiten.

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

Laden Sie die Datei und prüfen Sie, ob sie importiert wurde:

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

reload importiert die YAML-Datei mit den Ausgangsdaten in SQLite. list sollte jetzt den Agent mit einer ID ausgeben. Wenn list ihn nicht anzeigt, wurde die Datei nicht geparst. Der Grund dafür steht in .managed-agents/logs/runtime.log.

mcp_servers definiert MCP-Endpunkte (Model Context Protocol). type: url bedeutet, dass die Laufzeitumgebung per HTTP mit einem Server kommuniziert, der an einem anderen Ort ausgeführt wird. Daher können Sie jeden bereits betriebenen Server verwenden, einschließlich MCP-Servern, die auf demselben VPS wie die Laufzeitumgebung gehostet werden.

Durch die Definition eines Servers stehen seine Tools dem Agent noch nicht zur Verfügung. Dafür ist die Liste tools zuständig. Sie enthält einen Eintrag mcp_toolset, dessen mcp_server_name mit dem oben genannten name übereinstimmt. Wenn sich der Agent so verhält, als wären die MCP-Tools nicht vorhanden, vergleichen Sie diese beiden Zeichenfolgen Zeichen für Zeichen, bevor Sie an anderer Stelle suchen.

agent_toolset_20260401 ist der integrierte Tool-Satz. Das Suffix mit dem Datum ist eine Schema-Version. Dadurch behält ein daran gebundener Agent die Tool-Definitionen bei, für die er geschrieben wurde. default_config legt die Richtlinie für jedes Tool in diesem Satz fest. Jeder Eintrag unter configs überschreibt diese Richtlinie für ein einzelnes Tool anhand seines Namens, im Beispiel bash.

permission_policy ist der Bereich, in dem sich eine Laufzeitumgebung gegenüber einem einfachen Modellaufruf bewährt. always_ask hält die Sitzung an und wartet auf die Bestätigung eines Menschen, bevor der Aufruf ausgeführt wird. always_allow lässt den Aufruf zu. Wenn Sie bash auf always_ask setzen, kann der Agent keinen Shell-Befehl ausführen, ohne dass Sie zuvor den genauen Befehl sehen. Das ist dieselbe Kontrolle, die Sie beim sicheren Ausführen von Claude Code auf einem VPS verwenden würden.

Die drei Sandbox-Modi und wann welcher geeignet ist

Tool-Aufrufe, die Code ausführen, laufen innerhalb einer Sandbox. Das Backend wird pro Umgebung über sandbox_provider im Objekt config der Umgebung oder unter Settings und anschließend Sandbox in der Konsole festgelegt. Umgebungen werden über die API unter POST /v1/environments erstellt.

local führt den Code als untergeordneten Prozess der Laufzeitumgebung auf dem Host und unter dem Benutzer der Laufzeitumgebung aus. Dies ist die Standardeinstellung. Sie ist vertretbar, solange Sie der einzige Benutzer sind und der Agent ausschließlich Dateien liest, deren Eigentümer Sie sind. Dabei handelt es sich nicht um eine Isolation. Ein Tool-Aufruf, der Dateien löscht, löscht Ihre Dateien. Ein Tool-Aufruf, der /etc/sandbase/runtime.env liest, liest Ihren Provider-Schlüssel.

docker startet pro Sitzung einen Container.

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

Die Sitzung erhält ein eigenes Dateisystem, eine eigene Speicherobergrenze und einen eigenen CPU-Anteil. Der Container wird zusammen mit der Sitzung entfernt. Wechseln Sie zu diesem Modus, sobald ein Agent Code ausführt, den Sie nicht selbst geschrieben haben. Der Nachteil ist, dass der Benutzer der Laufzeitumgebung Zugriff auf den Docker-Socket benötigt. Die Mitgliedschaft in der Gruppe docker entspricht auf dem Host dem Zugriff als root. Container pro Sitzung haben denselben Aufbau wie Self-Hosted-Agent-Sandboxen mit einem Container pro Ausführung. Daher gilt die dortige Einschätzung, welche Ressourcen ein entwichener Prozess erreichen könnte, hier unverändert.

kubernetes führt die Sitzungs-Workload als Pod aus und steuert sie mit kubectl exec und kubectl cp. Im Laufzeit-Image muss kubectl vorhanden sein. Außerdem benötigt dessen ServiceAccount RBAC-Berechtigungen (Role-Based Access Control), um Pods im Ziel-Namespace zu erstellen, zu löschen, abzurufen, aufzulisten und zu überwachen, sowie Zugriff auf das Subresource exec. Dieser Modus lohnt den Einrichtungsaufwand nur, wenn Sie bereits einen Cluster betreiben.

Warum ist die Runtime an 127.0.0.1 gebunden?

Weil sie mit deaktivierter Authentifizierung startet. Die Runtime aktiviert die Bearer-Token-Authentifizierung, sobald mindestens ein API-Schlüssel vorhanden ist. Eine neue init legt jedoch keinen an. Würde sie in diesem Standardzustand an 0.0.0.0 gebunden, wäre eine nicht authentifizierte Agent-Runtime mit Shell-Tools und Ihrem Provider-Schlüssel im öffentlichen Internet erreichbar.

Wenn Sie die Runtime erreichbar machen möchten, lassen Sie die Bind-Adresse unverändert und führen Sie zwei andere Schritte aus.

Aktivieren Sie zuerst die Authentifizierung. Setzen Sie MANAGED_AGENTS_API_KEY in der Umgebungsdatei des Dienstes oder erstellen Sie mit POST /v1/api-keys einen Schlüssel. Der Befehl gibt einmalig ein Feld secret_key zurück und zeigt es danach nicht mehr an. Clients senden anschließend bei jeder Anfrage Authorization: Bearer <key>.

Schalten Sie zweitens einen Reverse Proxy davor und terminieren Sie dort TLS (Transport Layer Security). Die Runtime stellt absichtlich einfaches HTTP bereit und erwartet, dass ein anderer Dienst die Zertifikate verwaltet.

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;
    }
}

Zwei dieser Zeilen sind nicht nur Dekoration. proxy_buffering off ist relevant, weil Sitzungen über Server-Sent Events (SSE) gestreamt werden. Bei aktivierter Pufferung hält nginx die Antwort zurück, bis sein Puffer voll ist. Dadurch zeigt die Konsole nichts an, während der Agent arbeitet, und gibt anschließend alles auf einmal aus. proxy_read_timeout 3600s ist relevant, weil der Standardwert 60 Sekunden beträgt. Ein Stream, der länger als eine Minute keine Daten sendet, wird dann während eines Durchlaufs vom Proxy geschlossen. Der Fehler sieht dadurch so aus, als würde die Runtime abstürzen.

Öffnen Sie in der Firewall die Ports 22 und 443. Lassen Sie Port 3000 geschlossen, weil der Proxy ihn über Loopback erreicht und nichts außerhalb des Servers darauf zugreifen sollte.

Den Anthropic SDK auf den eigenen Server ausrichten

Die Laufzeit stellt eine CMA-kompatible /v1-Oberfläche bereit. Daher muss ein Anthropic-SDK-Client nur ein Feld ändern, um mit ihr zu kommunizieren.

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'
});

Sie akzeptiert außerdem die Beta-Header, die Claude-Managed-Agents-Clients senden: anthropic-beta: managed-agents-2026-04-01 und anthropic-beta: agent-memory-2026-07-22. Gegenüber einer lokalen Laufzeit sind sie optional. Sie ermöglichen, dass Code für eine gehostete Bereitstellung hier unverändert ausgeführt wird.

Die Kompatibilität ist weitgehend gegeben, aber nicht vollständig. Lesen Sie docs/api-matrix.md im Checkout, bevor Sie von einer vorhandenen Oberfläche ausgehen. Das Projekt dokumentiert dort auch eigene Lücken, darunter clientseitige benutzerdefinierte Tools. Diese benötigen weiterhin eine Registrierung mit Namen oberhalb des aktuellen Event-Result-Protokolls.

Einfaches HTTP funktioniert ebenfalls und ist der schnellste Weg, um zu prüfen, ob die Laufzeit aktiv ist:

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}'

Eine fehlerfreie Antwort ist ein Ereignis-Stream, in dem fortlaufend weitere Ereignisse eintreffen. Wenn die Verbindung abbricht, setzen Sie beim letzten empfangenen Ereignis fort, anstatt den gesamten Turn erneut abzuspielen:

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

Dank dieses fortsetzbaren Streams bleibt eine Sitzung auch nach dem Schließen des Laptops erhalten. Die Ereignisse werden auf dem Server gespeichert. Der Client spielt daher ein Protokoll ab, anstatt die einzige Kopie zu halten.

Wo Zugangsdaten, Speicher und Audit-Trails auf der Festplatte liegen

Alles, was der Runtime gehört, liegt unter .managed-agents/ im Workspace.

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

• data.db enthält die SQLite-Metadaten: Agents, Sitzungen, Einträge im Credential Vault, Einträge im Memory Store und API-Schlüssel.
• files/ enthält die Bytes hochgeladener Dateien, und skills/ enthält hochgeladene Skill-Pakete.
• snapshots/ enthält Snapshots der Sitzungs-Workspaces, und sandbox/ enthält die Arbeitsverzeichnisse von Sitzungen im Local Mode.
• logs/runtime.log ist die erste Anlaufstelle, wenn etwas ohne Fehlermeldung nicht funktioniert.

Credential Vaults sind Gruppen von Geheimnissen. Jedes Geheimnis wird mit einem auth_type wie environment_variable hinzugefügt und beim Erstellen über vault_ids einer Sitzung zugewiesen. Memory Stores enthalten benannte Einträge, die Sie als memory_store mit eigener Zugriffseinstellung und eigenen Anweisungen in eine Sitzung einbinden. Beide liegen in data.db. Genau das unterscheidet diesen Ansatz von einem direkten Modellaufruf: Die Runtime behält Informationen über Sitzungen hinweg und protokolliert, was passiert ist.

Da alles in einem Verzeichnis liegt, sichern Sie dieses Verzeichnis als Einheit.

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

Stoppen Sie zuerst den Dienst. Wenn Sie eine SQLite-Datenbank kopieren, während die Runtime darin schreibt, kann eine Datei entstehen, die sich bei der Wiederherstellung nicht öffnen lässt. Das bemerken Sie möglicherweise erst an dem Tag, an dem Sie die Sicherung benötigen. Wenn Sie Agent-YAML lieber in git und den Status an einem anderen Ort verwalten möchten, können Sie den Speicherort des Status in der Deployment-Dokumentation mit --data-dir auf start festlegen.

Die Wiederherstellung erfolgt in umgekehrter Reihenfolge: Checken Sie auf einem neuen System denselben Tag aus, entpacken Sie das Archiv in den Workspace und starten Sie den Dienst. Wenn Sie die Form ${OPENAI_API_KEY} verwendet haben, befindet sich der Provider-Schlüssel nicht im Archiv. Bewahren Sie ihn daher an einem Ort auf, auf den Sie weiterhin Zugriff haben.

Unter systemd ausführen

Geben Sie der Laufzeit einen eigenen Benutzer. So kann ein Tool-Aufruf im lokalen Sandbox-Modus nicht unter Ihrer Identität handeln.

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

Speichern Sie dies als /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

Das Deployment-Beispiel des Projekts ruft auf PATH ein managed-agents-Binary auf. Eine Installation aus markiertem Quellcode erstellt dieses Binary nicht. Daher führt ExecStart stattdessen node gegen den erstellten Einstiegspunkt aus.

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

Ein fehlerfreies Ergebnis ist active (running) von status und 200 von curl. Bei jedem anderen Ergebnis lesen Sie zuerst journalctl -u sandbase -n 50 und anschließend .managed-agents/logs/runtime.log. enable --now ist der entscheidende Teil, weil ein manuell gestarteter Prozess nach dem nächsten Reboot beendet ist.

Was fehlschlägt und welche Meldung angezeigt wird

npm run build wird von npm ohne Fehlermeldung beendet. Auf einem VPS mit 1 GB beendet der Out-of-Memory-Killer des Kernels die TypeScript-Kompilierung. Die Meldung wird in das Kernel-Log geschrieben und nicht an npm übergeben. Prüfen Sie dies mit journalctl -k | grep -i "out of memory". Der Befehl gibt eine Zeile aus, in der der beendete Prozess node genannt wird. Fügen Sie Swap hinzu oder erstellen Sie den Build auf einer größeren Instanz und kopieren Sie dist/ anschließend dorthin.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. Ein anderer Prozess verwendet den Port bereits. sudo ss -lntp | grep 3000 gibt den Prozess an. Beenden Sie ihn oder starten Sie die Runtime mit --port 3001 und aktualisieren Sie den Proxy.

Das Dashboard wird auf Ihrem Laptop nicht geladen. Das ist das erwartete Verhalten, weil die Runtime an die Loopback-Adresse gebunden ist. Verwenden Sie den SSH-Tunnel weiter oben oder schließen Sie die Konfiguration des Reverse Proxy ab. Beheben Sie das Problem nicht mit --host 0.0.0.0, weil die Authentifizierung deaktiviert bleibt, bis ein Schlüssel vorhanden ist.

Docker-Sandboxen schlagen mit permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock fehl. Der Benutzer sandbase gehört nicht zur Gruppe docker. Beheben Sie das mit sudo usermod -aG docker sandbase und starten Sie den Dienst neu. Beachten Sie dabei, welche Berechtigung Sie vergeben: Diese Gruppe entspricht auf dem Host root. Damit wird ein Teil des Sicherheitsvorteils aufgehoben, den ein eigener Benutzer für die Runtime bietet.

Kubernetes-Sandboxen schlagen mit Error from server (Forbidden) fehl. Dem ServiceAccount fehlen Berechtigungen für Pods oder für die Subressource exec. Prüfen Sie dies direkt mit kubectl auth can-i create pods/exec -n <namespace>. Der Befehl gibt yes oder no zurück.

Jede Anfrage gibt nach dem Hinzufügen eines API-Schlüssels 401 zurück. Die Authentifizierung wird aktiviert, sobald der erste Schlüssel vorhanden ist. Sie gilt sowohl für die Konsole als auch für die API. Senden Sie Authorization: Bearer <key>. Wenn Sie den Schlüssel verloren haben, erstellen Sie einen neuen, weil secret_key nur einmal zurückgegeben und nicht in lesbarer Form gespeichert wird.

Die Werkzeuge eines MCP-Servers erscheinen nie in einer Sitzung. Vergleichen Sie mcp_server_name im Block tools mit name in mcp_servers. Prüfen Sie anschließend mit curl -i <url>, ob die Runtime die URL vom Server selbst aus erreichen kann. Ein MCP-Server vom URL-Typ ist eine Netzwerkabhängigkeit. Ein VPS löst Namen auf und leitet Netzwerkverkehr anders weiter als Ihr Laptop.

FAQ

Kann ich SandBase Harness ohne einen OpenAI- oder Anthropic-Schlüssel ausführen?

Ja, wenn Sie einen OpenAI-kompatiblen Endpunkt haben. Die Laufzeit unterstützt OpenAI-, Anthropic- und OpenAI-kompatible Provider. Daher funktioniert auch ein lokaler Server, der die OpenAI-API bereitstellt. Legen Sie den Workspace-Provider in .managed-agents/config.yaml fest und tragen Sie den Endpunkt in api_key ein. Die Laufzeit enthält kein eigenes Modell. Ein Modell muss die Anfragen daher verarbeiten.

Ist es sicher, die Laufzeit an einem öffentlichen Port bereitzustellen?

Nicht mit der Standardkonfiguration. Die Laufzeit bindet an 127.0.0.1:3000 und startet ohne aktivierte Authentifizierung. Die Lösung ist nicht eine andere Bind-Adresse. Erstellen Sie einen API-Schlüssel oder setzen Sie MANAGED_AGENTS_API_KEY, damit die Bearer-Token-Authentifizierung aktiviert wird. Schalten Sie anschließend nginx oder Caddy für TLS davor. Lassen Sie Port 3000 in der Firewall geschlossen, damit der einzige Zugriffsweg über den Proxy führt.

Was ist der Unterschied zwischen den lokalen, Docker- und Kubernetes-Sandboxes?

local führt den Tool-Code als Kindprozess der Laufzeit auf dem Host aus, mit den Berechtigungen des Laufzeitbenutzers und ohne Isolation. docker erstellt für jede Sitzung einen eigenen Container mit eigenem Dateisystem, Speicherlimit und CPU-Anteil und entfernt ihn nach Ende der Sitzung. kubernetes führt die Sitzung als Pod aus und steuert sie mit kubectl exec. Dafür sind kubectl innerhalb des Laufzeit-Images sowie RBAC-Berechtigungen für Pods und die Ressource exec im Ziel-Namespace erforderlich.

Was muss ich genau sichern?

Das Verzeichnis .managed-agents/ im Workspace. Es enthält config.yaml, die data.db-SQLite-Datenbank mit Agents, Sitzungen, Einträgen im Credential Vault und Speichereinträgen sowie hochgeladene Dateien, Skill-Pakete und Sitzungs-Snapshots. Stoppen Sie den Dienst vor dem Kopieren, damit SQLite während der Archivierung nicht beschrieben wird. Provider-API-Schlüssel, auf die als ${OPENAI_API_KEY} verwiesen wird, sind nicht im Backup enthalten. Speichern Sie diese separat.

Warum sollte ich den Tag v0.3.2 statt main klonen?

Ein Tag bezeichnet einen unveränderlichen Quellbaum. Daher entsprechen die beschriebenen Konfigurationsschlüssel und CLI-Befehle genau der Version, die Sie tatsächlich erhalten. main ändert sich fortlaufend. Ein Konfigurationsschlüssel kann zwischen der Erstellung einer Anleitung und ihrer Ausführung umbenannt werden. Das Projekt weist außerdem darauf hin, dass das nicht auf einen Scope begrenzte npm-Paket managed-agents nicht zu diesem Projekt gehört. Daher installiert npx managed-agents etwas anderes. Release v0.3.1 ersetzt den npm-Schnellstart im Wesentlichen durch den Pfad über den festgelegten Quellcode-Tag.