Het contract
Een sidecar is een gRPC-server op een Unix-socket. Luister op het pad in NEBO_APP_SOCK en implementeer apps.v0.UIService. Nebo roept HandleRequest aan voor elk verzoek; HealthCheck en Configure horen bij de service, maar worden nu nog niet aangeroepen. De socket moet verschijnen binnen de startup_timeout van het manifest, die standaard 10 seconden is en maximaal 120 mag zijn.
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 draaien op macOS en Linux.
Waar Nebo de binary vindt
In de map van de app gebruikt Nebo de eerste die bestaat van:
- Een bestand met de naam
binary - Een bestand met de naam
app - Het eerste bestand in
tmp/ - Het eerste bestand in
bin/ - Het eerste uitvoerbare bestand in
sidecar/target/release/, voor lokale ontwikkeling
De binary moet een gewoon, uitvoerbaar bestand zijn, geen symbolische link, en maximaal 500 MB groot. Gepubliceerde apps hebben hem in bin/<name>. Als het bestand op schijf verandert, start Nebo de sidecar opnieuw.
Omgeving
De sidecar start met een lege omgeving en deze variabelen:
| Variabele | Waarde |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | De identiteit van de app. |
NEBO_APP_DIR | De map van de app. |
NEBO_APP_SOCK | De socket om op te luisteren, <app folder>/<id>.sock. Nebo zet de modus op 0600. |
NEBO_DATA_DIR | De datamap van de app, <data>/appdata/agents/<id>/. Ook de werkmap. |
NEBO_API_URL | De lokale API van de bot, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Een token om de app-API van de bot aan te roepen. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Doorgegeven. |
Standaarduitvoer en standaardfout gaan naar sidecar.log in de datamap. Standaardinvoer is een pipe; einde van het bestand betekent dat Nebo weg is en dat de sidecar moet afsluiten. De sidecar draait in zijn eigen procesgroep.
Verzoeken vanaf de pagina
Een verzoek naar /apps/<id>/api/<path>, dat de pagina doet met neboFetch en een relatief pad, komt bij HandleRequest aan met path ingesteld op <path>. Paden die met _ beginnen, worden geweigerd. De body van een verzoek is beperkt tot 10 MB en antwoorden tot 32 MB.
Tools voor de medewerker
Declareer tools in de agent.json van de app. Elke tool krijgt de naam app__<app>__<name> en wordt geladen wanneer de medewerker hem nodig heeft. Een aanroep wordt een verzoek aan de sidecar op method en 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 aanroepen
De sidecar kan dezelfde services gebruiken als de pagina door $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... aan te roepen met de header Authorization: Bearer $NEBO_APP_TOKEN.
| Route | Doet |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | De key-value-opslag van de app. |
POST /agents/invoke, POST /agents/stream | Vraagt iets aan een medewerker: {message, agent, data}. Streamantwoorden zijn server-sent events. |
POST /janus/complete, POST /janus/stream | Een directe modelaanroep: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Een extern verzoek, {url, method, headers, body}, toegestaan door de network:-machtigingen van de app. |
GET /identity | De medewerker van de app. |
Levenscyclus
- Nebo controleert de socket elke drie seconden.
- Een mislukte sidecar start na één seconde opnieuw, en die wachttijd verdubbelt tot maximaal 60 seconden. Na vijf mislukkingen op rij wordt hij als mislukt gemarkeerd. Een sidecar die 60 seconden blijft draaien, is weer gezond.
- Een verzoek aan een gestopte sidecar start hem en wacht maximaal 15 seconden. GET- en HEAD-verzoeken worden opnieuw geprobeerd.
- Om een sidecar te stoppen stuurt Nebo SIGTERM naar zijn procesgroep en beëindigt hem na twee seconden geforceerd.