SandBase Harness v0.3.2 selbst hosten

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

Self-Hosting der SandBase-Agent-Runtime bedeutet, SandBase Harness auf einem eigenen Server zu betreiben. Sitzungen, Zugangsdaten, Speicher und Audit-Protokolle liegen dadurch auf Ihrer Festplatte und nicht 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 Managed-Agent-API, angelehnt. Dadurch ist diese Runtime 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. Die TypeScript-Erstellung ist der aufwendigste Installationsschritt.
• Node.js 22 oder neuer sowie npm 10 oder neuer. Das sind die vom Projekt festgelegten Mindestversionen.
• git sowie einen API-Schlüssel für den von Ihnen verwendeten Modellanbieter.
• Docker, jedoch nur, wenn Sie Container-Sandboxen pro Sitzung verwenden möchten.

Ubuntu 24.04 stellt im eigenen Repository Node 18.19 bereit. Diese Version liegt unter der Mindestversion. 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 mit derjenigen node-Version ausgeführt wird, die die Shell findet.

SandBase aus dem Tag v0.3.2 installieren

Installieren Sie 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 exakt die im versionierten Lockfile festgehaltenen Versionen. Dadurch entspricht Ihr Arbeitsverzeichnis dem Stand, den die Maintainer getestet haben. npm install darf neuere Versionen auflösen. So kann ein fixierter Tag unbemerkt seine feste Versionierung verlieren.

Erstellen Sie nun einen Workspace. Der Workspace ist ein separates Verzeichnis für Ihre Agent-Dateien und den gesamten Laufzeitstatus. Wenn Sie ihn außerhalb des Source-Checkouts ablegen, 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 schreibt ein Verzeichnis .managed-agents/ in den Workspace. 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 vorerst über SSH auf die Konsole zu:

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

Der lange node .../dist/index.js-Pfad 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>.

Installieren Sie es nicht über npm

In der eigenen Installationsdokumentation weist das Projekt darauf hin: Das auf npm sichtbare nicht mit einem Scope versehene Paket managed-agents gehört nicht zu diesem Projekt. Daher laden npx managed-agents und npm install -g managed-agents etwas herunter, das nicht zu der gewünschten Laufzeitumgebung gehört. Installieren Sie das Projekt aus dem getaggten GitHub-Quellcode, bis die Maintainer ein offizielles Paket mit Scope bereitstellen. Das ist keine nebensächliche historische Anmerkung: v0.3.1 dient hauptsächlich dazu, den alten npm-Schnellstart durch den festgelegten Pfad über den getaggten Quellcode zu ersetzen.

Den Workspace mit einem Modellanbieter verbinden

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

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 sowohl aus der Konfigurationsdatei als auch aus jeder Sicherung dieser Datei heraus. Legen Sie ihn in einer Umgebungsdatei ab, die nur root lesen kann, da systemd EnvironmentFile= als root liest, bevor es die Berechtigungen reduziert.

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 die Zeile OPENAI_API_KEY=sk-... hinzu. Anbieterschlüssel gehören hierher. Geheimnisse, die ein Agent während einer Sitzung verwendet, gehören dagegen in die Credential-Vaults der Laufzeitumgebung. Das ist ein anderes Problem mit einem anderen Auswirkungsbereich. Geheimnisse von AI-Agents fernhalten sollten Sie lesen, bevor Sie an einer der beiden Stellen ein Produktions-Token einfügen.

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

Agents werden als YAML-Dateien im Workspace-Verzeichnis agents/ definiert. In diesem Teil der Laufzeitumgebung werden Sie tatsächlich die meiste Zeit arbeiten. Die Schlüssel werden verständlicher, sobald Sie eine kleine Agentenschleife manuell geschrieben haben, weil jeder Schlüssel eine Einstellung für etwas ist, das Sie sonst selbst programmieren müssten: den System-Prompt, die Tool-Liste und die Prüfung, die vor der Ausführung eines Tools läuft.

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 übernommen wurde:

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

reload importiert die Seed-YAML-Datei in SQLite. list sollte jetzt den Agent mit einer ID ausgeben. Wenn list ihn nicht anzeigt, wurde die Datei nicht geparst. .managed-agents/logs/runtime.log enthält den Grund.

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. Damit können Sie alles verwenden, was Sie bereits betreiben, einschließlich MCP-Servern, die auf demselben VPS wie die Laufzeitumgebung gehostet werden. Die Websuche ist normalerweise das erste Werkzeug, zu dem viele greifen. Bevor Sie einen solchen Dienst anbinden, sollten Sie einem Agenten Ihre eigene SearXNG-Instanz übergeben lesen, da ein Werkzeug, das von Dritten verfasste Seiten zurückgibt, nicht vertrauenswürdigen Text direkt in den Kontext des Modells einfügt. Der unkritischere Einstieg ist die umgekehrte Variante: ein schreibgeschützter Endpunkt für Daten, die Sie bereits besitzen. Genau das stellt openGym direkt neben dem Trainingstracker bereit. Der Agent kann dadurch Fragen zu Ihrer Trainingshistorie beantworten, ohne sie ändern zu können.

Die Deklaration eines Servers stellt dessen Tools dem Agent nicht zur Verfügung. Die Liste tools übernimmt diese Aufgabe. Dazu dient ein mcp_toolset-Eintrag, 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 das integrierte Toolset. Das Suffix mit dem Datum ist eine Schema-Version. Ein daran gebundener Agent behält dadurch die Tool-Definitionen bei, für die er geschrieben wurde. default_config legt die Richtlinie für jedes Tool im Set fest. Jeder Eintrag unter configs überschreibt diese Richtlinie für ein Tool anhand seines Namens, im Beispiel bash.

permission_policy ist der Bereich, in dem sich eine Laufzeitumgebung gegenüber einem einfachen Modellaufruf auszeichnet. always_ask hält die Sitzung an und wartet auf die Freigabe durch einen Menschen, bevor der Aufruf ausgeführt wird. always_allow lässt ihn passieren. Wenn Sie bash auf always_ask setzen, kann der Agent keinen Shell-Befehl ausführen, ohne dass Sie zuvor den exakten Befehl sehen. Das ist dieselbe Kontrolle, die Sie beim sicheren Ausführen von Claude Code auf einem VPS verwenden würden. Wenn Sie zusätzlich DeepSeek Harness betreiben, stehen Ihnen dieselben Kontrollen dort als Erweiterungen statt als YAML-Schlüssel zur Verfügung. Die Plugins zur Begrenzung von Budgets und zur Freigabe von Tool-Aufrufen sind das nächstliegende Gegenstück zu diesem Block.

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 config-Objekt der Umgebung oder in der Konsole unter Settings und anschließend Sandbox ausgewählt. Umgebungen werden über die API unter POST /v1/environments erstellt.

local führt den Code als Kindprozess 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 nur Dateien liest, deren Eigentümer Sie sind. Dabei findet keine Isolation statt. 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, ein eigenes Speicherlimit und einen eigenen CPU-Anteil. Der Container wird zusammen mit der Sitzung entfernt. Wechseln Sie sofort zu diesem Modus, sobald ein Agent Code ausführt, den Sie nicht selbst geschrieben haben. Der Nachteil besteht darin, dass der Benutzer der Laufzeitumgebung Zugriff auf den Docker-Socket benötigt. Die Mitgliedschaft in der Gruppe docker entspricht auf dem Host faktisch root-Rechten. Container pro Sitzung haben dieselbe Struktur wie Self-Hosted-Agent-Sandboxen mit einem Container pro Ausführung. Daher gilt die Überlegung, welche Ressourcen ein ausgebrochener 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. Der ServiceAccount benötigt RBAC-Berechtigungen (Role-Based Access Control), um im Ziel-Namespace Pods zu erstellen, zu löschen, abzurufen, aufzulisten und zu überwachen. Außerdem ist Zugriff auf die Subressource exec erforderlich. Dieser Modus lohnt den Einrichtungsaufwand nur, wenn Sie bereits einen Cluster betreiben.

Warum ist die Runtime an 127.0.0.1 gebunden?

Weil sie ohne aktivierte Authentifizierung startet. Die Runtime aktiviert die Bearer-Token-Authentifizierung, sobald mindestens ein API-Schlüssel vorhanden ist. Eine neue init erstellt jedoch keinen Schlüssel. Eine Bindung an 0.0.0.0 würde diese nicht authentifizierte Agent-Runtime mit ihren Shell-Tools und Ihrem Provider-Schlüssel in diesem Standardzustand im öffentlichen Internet erreichbar machen.

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 erneut an. Clients senden Authorization: Bearer <key> anschließend bei jeder Anfrage. Ein Schlüssel entspricht einer gemeinsamen Identität. Wenn Sie stattdessen für jedes Teammitglied einen eigenen isolierten Agenten mit zentral im Gateway verwalteten Provider-Schlüsseln benötigen, ist OneCLI für dieses Modell ausgelegt.

Setzen Sie zweitens einen Reverse Proxy davor und terminieren Sie dort TLS (Transport Layer Security). Die Runtime stellt absichtlich einfaches HTTP bereit und erwartet, dass eine andere Komponente 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 optional. proxy_buffering off ist wichtig, weil Sitzungen über Server-Sent Events (SSE) gestreamt werden. Bei aktivierter Pufferung hält nginx die Antwort zurück, bis sein Puffer gefüllt ist. Die Konsole zeigt dann während der Verarbeitung durch den Agenten nichts an und gibt anschließend alles auf einmal aus. proxy_read_timeout 3600s ist wichtig, weil der Standardwert 60 Sekunden beträgt. Ein Stream, der länger als eine Minute keine Daten sendet, wird daher während eines Durchlaufs vom Proxy geschlossen. Der Fehler sieht dann 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 Ihren eigenen Rechner richten

Die Laufzeit stellt eine CMA-ähnliche /v1-Schnittstelle bereit. Daher kommuniziert ein Anthropic SDK-Client mit ihr, wenn Sie ein Feld ändern.

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 eine lokale Laufzeit sind sie optional. Sie sorgen dafür, dass Code für eine gehostete Bereitstellung hier unverändert ausgeführt werden kann.

Die Kompatibilität ist weitgehend gegeben, aber nicht vollständig. Lesen Sie docs/api-matrix.md im Checkout, bevor Sie von einer vorhandenen Schnittstelle ausgehen. Das Projekt dokumentiert dort seine Einschränkungen, darunter clientseitige benutzerdefinierte Tools, die weiterhin eine Registrierung mit Namen oberhalb des aktuellen Event-Result-Protokolls benötigen.

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

Bei einer funktionsfähigen Antwort trifft fortlaufend ein Stream von Events ein. Wenn die Verbindung abbricht, setzen Sie die Übertragung ab dem letzten empfangenen Event fort, statt 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 Session auch nach dem Schließen des Laptops erhalten. Die Events werden auf dem Server persistiert. Der Client spielt daher ein Log ab, statt die einzige Kopie vorzuhalten.

Wo Anmeldedaten, Arbeitsspeicher und Audit-Protokolle auf der Festplatte liegen

Alles, was die Laufzeitumgebung verwaltet, 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 Anmeldedatenspeicher, 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 Stelle, die Sie prüfen sollten, wenn etwas ohne Fehlermeldung nichts tut.

Credential Vaults sind Gruppen von Geheimnissen. Jedes Geheimnis wird mit einem auth_type wie environment_variable hinzugefügt und beim Erstellen über vault_ids an eine Sitzung angehängt. Memory Stores enthalten benannte Einträge, die Sie als memory_store mit einer eigenen Zugriffseinstellung und eigenen Anweisungen in eine Sitzung einbinden. Beide liegen in data.db. Genau das unterscheidet diesen Ansatz von einem direkten Model-Call: Die Laufzeitumgebung speichert 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 Laufzeitumgebung 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 die Agent-YAML-Dateien lieber in git und den Status an einem anderen Ort verwalten möchten, unterstützt die Deployment-Dokumentation das Festlegen des Statuspfads mit --data-dir auf start.

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

Unter systemd ausführen

Weisen Sie der Laufzeit einen eigenen Benutzer zu. Ein Tool-Aufruf im lokalen Sandbox-Modus kann dann nicht als Ihr Benutzer 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 eigene Bereitstellungsbeispiel des Projekts ruft auf PATH eine managed-agents-Binärdatei auf. Eine Installation aus getaggten Quellen erstellt keine solche Datei. Daher führt ExecStart stattdessen node für 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 ordnungsgemäßes Ergebnis ist active (running) von status und 200 von curl. Bei jedem anderen Ergebnis lesen Sie zuerst journalctl -u sandbase -n 50 und danach .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 Sie sehen

npm run build wird ohne Fehlermeldung von npm beendet. Auf einem VPS mit 1 GB beendet der Out-of-Memory-Killer des Kernels die TypeScript-Kompilierung. Die Meldung steht im Kernel-Log und nicht in npm. Bestätigen 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/ 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 zeigt diesen Prozess an. Beenden Sie entweder den Prozess oder starten Sie die Laufzeit mit --port 3001 und aktualisieren Sie den Proxy.

Das Dashboard wird auf Ihrem Laptop nicht geladen. Das ist beabsichtigt, weil die Laufzeit an Loopback gebunden ist. Verwenden Sie den SSH-Tunnel weiter oben oder richten Sie den Reverse Proxy fertig ein. 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 dies mit sudo usermod -aG docker sandbase und starten Sie den Dienst neu. Beachten Sie dabei, welche Berechtigungen Sie vergeben: Diese Gruppe hat auf dem Host root-Berechtigungen. Dadurch wird ein Teil des Sicherheitsvorteils aufgehoben, den ein eigener Benutzer für die Laufzeit bietet.

Kubernetes-Sandboxen schlagen mit Error from server (Forbidden) fehl. Für den ServiceAccount fehlen Pod-Berechtigungen oder die Berechtigung 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 für die Konsole ebenso wie 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 Tools eines MCP-Servers werden in einer Sitzung nie angezeigt. Vergleichen Sie mcp_server_name im Block tools mit name in mcp_servers. Prüfen Sie anschließend mit curl -i <url>, ob die Laufzeit die URL vom Server selbst aus erreichen kann. Ein MCP-Server vom Typ URL 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 Anbieter. Daher funktioniert auch ein lokaler Server, der die OpenAI API bereitstellt. Legen Sie den Provider des Workspace in .managed-agents/config.yaml fest und verweisen Sie api_key sowie den Endpunkt darauf. Die Laufzeit enthält kein eigenes Modell. Daher muss ein anderer Dienst die Anfragen beantworten.

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

Nicht in der Standardkonfiguration. Die Laufzeit bindet an 127.0.0.1:3000 und startet ohne aktivierte Authentifizierung. Eine andere Bind-Adresse behebt das Problem nicht. 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 Zugangsweg über den Proxy führt.

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

local führt 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 am Ende der Sitzung. kubernetes führt die Sitzung als Pod aus und steuert ihn mit kubectl exec. Dafür werden kubectl im Laufzeit-Image sowie RBAC-Berechtigungen für Pods und die Subressource exec im Ziel-Namespace benötigt.

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 Sitzungssnapshots. Beenden Sie den Dienst, bevor Sie das Verzeichnis kopieren, damit SQLite während des Archivierens nicht beschrieben wird. Provider-API-Schlüssel, auf die als ${OPENAI_API_KEY} verwiesen wird, sind nicht in der Sicherung enthalten. Speichern Sie diese daher separat.

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

Ein Tag bezeichnet einen festen Quellbaum. Daher erhalten Sie genau die Konfigurationsschlüssel und CLI-Befehle, die in der Dokumentation beschrieben sind. main ändert sich, und ein Konfigurationsschlüssel kann zwischen dem Erstellen einer Anleitung und ihrer Ausführung umbenannt werden. Das Projekt weist außerdem darauf hin, dass das nicht auf einen Scope festgelegte managed-agents-Paket auf npm nicht zu diesem Projekt gehört. Daher installiert npx managed-agents etwas anderes. Release v0.3.1 ersetzt hauptsächlich den schnellen npm-Einstieg durch den auf den markierten Quellcode festgelegten Installationsweg.