NeboAI
NeboAI
Loslegen

App-Sidecar

Ein Sidecar ist eine Binärdatei, die neben einer App läuft. Er stellt die API der Seite bereit, hält die Daten der App und gibt dem Mitarbeiter der App Tools. Nebo startet ihn, leitet Anfragen über einen lokalen Socket an ihn weiter und startet ihn neu, wenn er ausfällt.

Der Vertrag

Ein Sidecar ist ein gRPC-Server auf einem Unix-Socket. Lausche auf dem Pfad in NEBO_APP_SOCK und implementiere apps.v0.UIService. Nebo ruft HandleRequest für jede Anfrage auf; HealthCheck und Configure gehören zum Dienst, werden derzeit aber nicht aufgerufen. Der Socket muss innerhalb des startup_timeout aus dem Manifest erscheinen, der standardmäßig 10 Sekunden beträgt und höchstens 120 sein darf.

syntax = "proto3";
package apps.v0;

service UIService {
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Configure(SettingsMap) returns (Empty);
  rpc HandleRequest(HttpRequest) returns (HttpResponse);
}

message HttpRequest {
  string method = 1;               // GET, POST, PUT, DELETE, ...
  string path = 2;                 // relative to /apps/{id}/api/
  string query = 3;                // raw query string
  map<string, string> headers = 4;
  bytes body = 5;
}

message HttpResponse {
  int32 status_code = 1;
  map<string, string> headers = 2;
  bytes body = 3;
}

Sidecars laufen unter macOS und Linux.

Wo Nebo die Binärdatei findet

Im Ordner der App nutzt Nebo die erste dieser Dateien, die existiert:

  1. Eine Datei namens binary
  2. Eine Datei namens app
  3. Die erste Datei in tmp/
  4. Die erste Datei in bin/
  5. Die erste ausführbare Datei in sidecar/target/release/, für die lokale Entwicklung

Die Binärdatei muss eine reguläre, ausführbare Datei sein, kein symbolischer Link, und höchstens 500 MB groß. Veröffentlichte Apps liefern sie unter bin/<name> mit. Wenn sich die Datei auf der Festplatte ändert, startet Nebo den Sidecar neu.

Umgebung

Der Sidecar startet mit einer leeren Umgebung und diesen Variablen:

VariableWert
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONDie Identität der App.
NEBO_APP_DIRDer Ordner der App.
NEBO_APP_SOCKDer Socket, auf dem gelauscht wird, <app folder>/<id>.sock. Nebo setzt seinen Modus auf 0600.
NEBO_DATA_DIRDer Datenordner der App, <data>/appdata/agents/<id>/. Gleichzeitig das Arbeitsverzeichnis.
NEBO_API_URLDie lokale API des Bots, http://127.0.0.1:<port>.
NEBO_APP_TOKENEin Token für Aufrufe der App-API des Bots.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZDurchgereicht.

Standardausgabe und Standardfehlerausgabe gehen in sidecar.log im Datenordner. Die Standardeingabe ist eine Pipe; Dateiende bedeutet, dass Nebo nicht mehr da ist und der Sidecar sich beenden sollte. Der Sidecar läuft in einer eigenen Prozessgruppe.

Anfragen von der Seite

Eine Anfrage an /apps/<id>/api/<path>, die die Seite mit neboFetch und einem relativen Pfad stellt, erreicht HandleRequest mit path auf <path> gesetzt. Pfade, die mit _ beginnen, werden abgelehnt. Anfragen sind auf 10 MB begrenzt, Antworten auf 32 MB.

Tools für den Mitarbeiter

Lege Tools in der agent.json der App fest. Jedes wird zu einem Tool namens app__<app>__<name>, das geladen wird, wenn der Mitarbeiter es braucht. Ein Aufruf wird zu einer Anfrage an den Sidecar unter method und path.

"tools": [
  {
    "name": "list_deals",
    "description": "List open deals, optionally filtered by stage.",
    "method": "GET",
    "path": "/deals",
    "input_schema": { "type": "object", "properties": { "stage": { "type": "string" } } }
  }
]

Nebo aufrufen

Der Sidecar kann dieselben Dienste wie die Seite nutzen, indem er $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... mit dem Header Authorization: Bearer $NEBO_APP_TOKEN aufruft.

RouteFunktion
GET /storage, GET|PUT|DELETE /storage/<key>Der Key-Value-Speicher der App.
POST /agents/invoke, POST /agents/streamFragt einen Mitarbeiter: {message, agent, data}. Stream-Antworten sind Server-Sent Events.
POST /janus/complete, POST /janus/streamEin direkter Modellaufruf: {messages, model, temperature, max_tokens, system}.
POST /http/proxyEine externe Anfrage, {url, method, headers, body}, erlaubt durch die network:-Berechtigungen der App.
GET /identityDer Mitarbeiter der App.

Lebenszyklus

  • Nebo prüft den Socket alle drei Sekunden.
  • Ein ausgefallener Sidecar startet nach einer Sekunde neu, die Wartezeit verdoppelt sich bis höchstens 60 Sekunden. Nach fünf Ausfällen in Folge wird er als fehlgeschlagen markiert. Ein Sidecar, der 60 Sekunden lang läuft, gilt wieder als gesund.
  • Eine Anfrage an einen gestoppten Sidecar startet ihn und wartet bis zu 15 Sekunden. GET- und HEAD-Anfragen werden wiederholt.
  • Um einen Sidecar zu stoppen, sendet Nebo SIGTERM an seine Prozessgruppe und beendet ihn nach zwei Sekunden zwangsweise.