Il contratto
Un sidecar è un server gRPC su un socket Unix. Mettiti in ascolto sul percorso indicato in NEBO_APP_SOCK e implementa apps.v0.UIService. Nebo chiama HandleRequest per ogni richiesta; HealthCheck e Configure fanno parte del servizio ma oggi non vengono chiamati. Il socket deve comparire entro lo startup_timeout del manifest, che per impostazione predefinita è di 10 secondi e può arrivare al massimo a 120.
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;
} I sidecar girano su macOS e Linux.
Dove Nebo trova il binario
Nella cartella dell’app, Nebo usa il primo di questi che esiste:
- Un file chiamato
binary - Un file chiamato
app - Il primo file in
tmp/ - Il primo file in
bin/ - Il primo eseguibile in
sidecar/target/release/, per lo sviluppo locale
Il binario deve essere un file normale ed eseguibile, non un link simbolico, e al massimo di 500 MB. Le app pubblicate lo contengono in bin/<name>. Quando il file cambia su disco, Nebo riavvia il sidecar.
Ambiente
Il sidecar si avvia con un ambiente vuoto e con queste variabili:
| Variabile | Valore |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | L’identità dell’app. |
NEBO_APP_DIR | La cartella dell’app. |
NEBO_APP_SOCK | Il socket su cui mettersi in ascolto, <app folder>/<id>.sock. Nebo ne imposta la modalità a 0600. |
NEBO_DATA_DIR | La cartella dei dati dell’app, <data>/appdata/agents/<id>/. È anche la cartella di lavoro. |
NEBO_API_URL | L’API locale del bot, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Un token per chiamare l’API delle app del bot. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Trasmessa così com’è. |
Lo standard output e lo standard error vanno in sidecar.log nella cartella dei dati. Lo standard input è una pipe; la fine del file significa che Nebo non c’è più e il sidecar deve terminare. Il sidecar gira nel proprio gruppo di processi.
Richieste dalla pagina
Una richiesta a /apps/<id>/api/<path>, che la pagina fa con neboFetch e un percorso relativo, arriva a HandleRequest con path impostato su <path>. I percorsi che iniziano con _ vengono rifiutati. Il corpo delle richieste è limitato a 10 MB e quello delle risposte a 32 MB.
Strumenti per il dipendente
Dichiara gli strumenti nell’agent.json dell’app. Ognuno diventa uno strumento chiamato app__<app>__<name>, caricato quando il dipendente ne ha bisogno. Una chiamata diventa una richiesta al sidecar su method e 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" } } }
}
] Chiamare Nebo
Il sidecar può usare gli stessi servizi della pagina chiamando $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... con l’header Authorization: Bearer $NEBO_APP_TOKEN.
| Percorso | Cosa fa |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | L’archivio chiave-valore dell’app. |
POST /agents/invoke, POST /agents/stream | Fa una domanda a un dipendente: {message, agent, data}. Le risposte in streaming sono server-sent event. |
POST /janus/complete, POST /janus/stream | Una chiamata diretta al modello: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Una richiesta esterna, {url, method, headers, body}, consentita dai permessi network: dell’app. |
GET /identity | Il dipendente dell’app. |
Ciclo di vita
- Nebo verifica il socket ogni tre secondi.
- Un sidecar che si è bloccato si riavvia dopo un secondo, raddoppiando fino a un massimo di 60 secondi. Dopo cinque errori di fila viene segnato come non riuscito. Un sidecar che resta attivo per 60 secondi torna a essere considerato funzionante.
- Una richiesta a un sidecar fermo lo avvia e attende fino a 15 secondi. Le richieste GET e HEAD vengono ritentate.
- Per fermare un sidecar, Nebo invia SIGTERM al suo gruppo di processi e lo termina forzatamente dopo due secondi.