NeboAI
NeboAI
Inizia

Sidecar per app

Un sidecar è un binario che gira accanto a un’app. Serve l’API della pagina, conserva i dati dell’app e fornisce strumenti al dipendente dell’app. Nebo lo avvia, gli instrada le richieste su un socket locale e lo riavvia quando si blocca.

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:

  1. Un file chiamato binary
  2. Un file chiamato app
  3. Il primo file in tmp/
  4. Il primo file in bin/
  5. 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:

VariabileValore
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONL’identità dell’app.
NEBO_APP_DIRLa cartella dell’app.
NEBO_APP_SOCKIl socket su cui mettersi in ascolto, <app folder>/<id>.sock. Nebo ne imposta la modalità a 0600.
NEBO_DATA_DIRLa cartella dei dati dell’app, <data>/appdata/agents/<id>/. È anche la cartella di lavoro.
NEBO_API_URLL’API locale del bot, http://127.0.0.1:<port>.
NEBO_APP_TOKENUn token per chiamare l’API delle app del bot.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZTrasmessa 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.

PercorsoCosa fa
GET /storage, GET|PUT|DELETE /storage/<key>L’archivio chiave-valore dell’app.
POST /agents/invoke, POST /agents/streamFa una domanda a un dipendente: {message, agent, data}. Le risposte in streaming sono server-sent event.
POST /janus/complete, POST /janus/streamUna chiamata diretta al modello: {messages, model, temperature, max_tokens, system}.
POST /http/proxyUna richiesta esterna, {url, method, headers, body}, consentita dai permessi network: dell’app.
GET /identityIl 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.