El contrato
Un sidecar es un servidor gRPC sobre un socket Unix. Escucha en la ruta de NEBO_APP_SOCK e implementa apps.v0.UIService. Nebo llama a HandleRequest en cada solicitud; HealthCheck y Configure forman parte del servicio, pero hoy no se llaman. El socket debe aparecer dentro del startup_timeout del manifiesto, que por defecto es de 10 segundos y como máximo puede ser de 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;
} Los sidecars funcionan en macOS y Linux.
Dónde busca Nebo el binario
En la carpeta de la app, Nebo usa el primero de estos que exista:
- Un archivo llamado
binary - Un archivo llamado
app - El primer archivo de
tmp/ - El primer archivo de
bin/ - El primer ejecutable de
sidecar/target/release/, para el desarrollo local
El binario debe ser un archivo normal y ejecutable, no un enlace simbólico, y ocupar como máximo 500 MB. Las apps publicadas lo llevan en bin/<name>. Cuando el archivo cambia en el disco, Nebo reinicia el sidecar.
Entorno
El sidecar se inicia con un entorno vacío y estas variables:
| Variable | Valor |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | La identidad de la app. |
NEBO_APP_DIR | La carpeta de la app. |
NEBO_APP_SOCK | El socket en el que escuchar, <app folder>/<id>.sock. Nebo establece su modo en 0600. |
NEBO_DATA_DIR | La carpeta de datos de la app, <data>/appdata/agents/<id>/. También es el directorio de trabajo. |
NEBO_API_URL | La API local del bot, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Un token para llamar a la API de apps del bot. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Se transmite tal cual. |
La salida estándar y la salida de error van a sidecar.log, en la carpeta de datos. La entrada estándar es una tubería; el fin de archivo significa que Nebo se ha ido y que el sidecar debe salir. El sidecar se ejecuta en su propio grupo de procesos.
Solicitudes de la página
Una solicitud a /apps/<id>/api/<path>, que la página hace con neboFetch y una ruta relativa, llega a HandleRequest con path establecido en <path>. Las rutas que empiezan por _ se rechazan. El cuerpo de las solicitudes tiene un límite de 10 MB y el de las respuestas, de 32 MB.
Herramientas para el empleado
Declara las herramientas en el agent.json de la app. Cada una se convierte en una herramienta llamada app__<app>__<name>, que se carga cuando el empleado la necesita. Cada llamada se convierte en una solicitud al sidecar en method y 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" } } }
}
] Llamar a Nebo
El sidecar puede usar los mismos servicios que la página llamando a $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... con la cabecera Authorization: Bearer $NEBO_APP_TOKEN.
| Ruta | Qué hace |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | El almacén de clave-valor de la app. |
POST /agents/invoke, POST /agents/stream | Pregunta a un empleado: {message, agent, data}. Las respuestas en streaming son eventos enviados por el servidor. |
POST /janus/complete, POST /janus/stream | Una llamada directa al modelo: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Una solicitud externa, {url, method, headers, body}, permitida por los permisos network: de la app. |
GET /identity | El empleado de la app. |
Ciclo de vida
- Nebo sondea el socket cada tres segundos.
- Un sidecar que falla se reinicia al cabo de un segundo, y el tiempo se duplica hasta un máximo de 60 segundos. Tras cinco fallos seguidos, se marca como fallido. Un sidecar que se mantiene en marcha durante 60 segundos vuelve a considerarse sano.
- Una solicitud a un sidecar detenido lo inicia y espera hasta 15 segundos. Las solicitudes GET y HEAD se reintentan.
- Para detener un sidecar, Nebo envía SIGTERM a su grupo de procesos y lo mata al cabo de dos segundos.