Le contrat
Un sidecar est un serveur gRPC sur un socket Unix. Écoutez sur le chemin indiqué par NEBO_APP_SOCK et implémentez apps.v0.UIService. Nebo appelle HandleRequest pour chaque requête ; HealthCheck et Configure font partie du service mais ne sont pas appelés aujourd'hui. Le socket doit apparaître dans le délai startup_timeout du manifeste, qui est de 10 secondes par défaut et peut aller jusqu'à 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;
} Les sidecars fonctionnent sur macOS et Linux.
Où Nebo trouve le binaire
Dans le dossier de l'application, Nebo utilise le premier de ces éléments qui existe :
- Un fichier nommé
binary - Un fichier nommé
app - Le premier fichier de
tmp/ - Le premier fichier de
bin/ - Le premier exécutable de
sidecar/target/release/, pour le développement local
Le binaire doit être un fichier ordinaire et exécutable, pas un lien symbolique, et peser au maximum 500 MB. Les applications publiées le placent dans bin/<name>. Quand le fichier change sur le disque, Nebo redémarre le sidecar.
Environnement
Le sidecar démarre avec un environnement vide et les variables suivantes :
| Variable | Valeur |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | L'identité de l'application. |
NEBO_APP_DIR | Le dossier de l'application. |
NEBO_APP_SOCK | Le socket sur lequel écouter, <app folder>/<id>.sock. Nebo règle ses droits sur 0600. |
NEBO_DATA_DIR | Le dossier de données de l'application, <data>/appdata/agents/<id>/. C'est aussi le répertoire de travail. |
NEBO_API_URL | L'API locale du bot, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Un jeton pour appeler l'API d'application du bot. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Transmise telle quelle. |
La sortie standard et la sortie d'erreur vont dans sidecar.log, dans le dossier de données. L'entrée standard est un pipe ; une fin de fichier signifie que Nebo est parti et que le sidecar doit s'arrêter. Le sidecar s'exécute dans son propre groupe de processus.
Requêtes de la page
Une requête vers /apps/<id>/api/<path>, que la page effectue avec neboFetch et un chemin relatif, arrive à HandleRequest avec path défini sur <path>. Les chemins qui commencent par _ sont refusés. Le corps des requêtes est limité à 10 MB et celui des réponses à 32 MB.
Outils pour l'employé
Déclarez les outils dans l’agent.json de l'application. Chacun devient un outil nommé app__<app>__<name>, chargé lorsque l'employé en a besoin. Un appel devient une requête vers le sidecar selon method et 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" } } }
}
] Appeler Nebo
Le sidecar peut utiliser les mêmes services que la page en appelant $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... avec l'en-tête Authorization: Bearer $NEBO_APP_TOKEN.
| Route | Rôle |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | Le magasin clé-valeur de l'application. |
POST /agents/invoke, POST /agents/stream | Interroge un employé : {message, agent, data}. Les réponses en streaming sont des server-sent events. |
POST /janus/complete, POST /janus/stream | Un appel direct au modèle : {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Une requête externe, {url, method, headers, body}, autorisée par les permissions network: de l'application. |
GET /identity | L'employé de l'application. |
Cycle de vie
- Nebo sonde le socket toutes les trois secondes.
- Un sidecar en échec redémarre au bout d'une seconde, puis le délai double jusqu'à 60 secondes au maximum. Après cinq échecs consécutifs, il est marqué en échec. Un sidecar qui reste actif pendant 60 secondes est de nouveau considéré comme sain.
- Une requête vers un sidecar arrêté le démarre et attend jusqu'à 15 secondes. Les requêtes GET et HEAD sont relancées.
- Pour arrêter un sidecar, Nebo envoie SIGTERM à son groupe de processus, puis le tue au bout de deux secondes.