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:
- Eine Datei namens
binary - Eine Datei namens
app - Die erste Datei in
tmp/ - Die erste Datei in
bin/ - 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:
| Variable | Wert |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | Die Identität der App. |
NEBO_APP_DIR | Der Ordner der App. |
NEBO_APP_SOCK | Der Socket, auf dem gelauscht wird, <app folder>/<id>.sock. Nebo setzt seinen Modus auf 0600. |
NEBO_DATA_DIR | Der Datenordner der App, <data>/appdata/agents/<id>/. Gleichzeitig das Arbeitsverzeichnis. |
NEBO_API_URL | Die lokale API des Bots, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Ein Token für Aufrufe der App-API des Bots. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Durchgereicht. |
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.
| Route | Funktion |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | Der Key-Value-Speicher der App. |
POST /agents/invoke, POST /agents/stream | Fragt einen Mitarbeiter: {message, agent, data}. Stream-Antworten sind Server-Sent Events. |
POST /janus/complete, POST /janus/stream | Ein direkter Modellaufruf: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Eine externe Anfrage, {url, method, headers, body}, erlaubt durch die network:-Berechtigungen der App. |
GET /identity | Der 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.