Descripción general
Qué es Nebo
Nebo es un asistente personal de IA para escritorio: un empleado de IA siempre activo que administra tu vida digital. Piensa en Nebo como piensas en un smartphone: una plataforma potente que se vuelve transformadora gracias a sus apps.
Por sí solo, Nebo ya es un empleado de IA capaz, con memoria, programación de tareas, navegación web, gestión de archivos y acceso a la terminal. Pero lo que realmente lo potencia son las apps. Así como el poder de un smartphone viene de su ecosistema de apps, el poder de Nebo viene de las apps que amplían lo que puede hacer.
Qué son las apps
Las apps de Nebo son unidades independientes y precompiladas con una funcionalidad increíble. Cada app le da a Nebo un nuevo superpoder: gestión de calendario, clasificación de correos, seguimiento de proyectos, domótica, análisis financiero… todo lo que un desarrollador pueda imaginar.
Las apps ofrecen un poder increíble de una forma muy segura. Cada app se ejecuta en un sandbox con permisos denegados por defecto. Solo puede acceder a lo que declara su manifiesto y el usuario aprueba.
La interfaz es 100 % conversacional. Los usuarios no interactúan con las apps desde pantallas o paneles separados. Hablan con Nebo, y Nebo usa las herramientas de la app para hacer el trabajo. "¿Qué tengo en el calendario mañana?": Nebo llama a la app de calendario. "Crea una reunión con Sarah a las 3 p. m.": Nebo llama a la app de calendario. El usuario nunca sale de la conversación.
Las apps pueden ofrecer, de forma opcional, una interfaz de configuración: un panel que se abre en la ventana del navegador integrado de Nebo. Ahí los usuarios ingresan claves de API, activan funciones y configuran la app. Esta interfaz se genera a partir del arreglo settings del manifiesto (Nebo dibuja el formulario automáticamente), o la app puede ofrecer su propia interfaz personalizada completa mediante la capacidad ui.
Las apps reemplazan y amplían las capacidades integradas de Nebo. Nebo incluye herramientas básicas de la plataforma (acceso al calendario local, capturas de pantalla, etc.). Cuando instalas una app de calendario, esta reemplaza la herramienta de calendario integrada y la supera: local + nube + agregación + verificación de disponibilidad.
Política de solo compilados
Nebo aplica una política estricta de solo binarios compilados. Todas las apps deben ser ejecutables nativos compilados.
| Estado | Lenguajes |
|---|---|
| Compatibles | Go (recomendado), Rust, C/C++, Zig |
| Rechazados | Python, Node.js, Ruby, Java, .NET, scripts de shell |
Justificación:
- Prevención de la automodificación de la IA: un empleado de IA con acceso a la terminal podría modificar el comportamiento de un script interpretado en tiempo de ejecución. Los binarios compilados son inmutables después de firmarse.
- Integridad de la firma: las firmas Ed25519 cubren los bytes del binario. Un binario firmado no se puede modificar sin invalidar la firma.
- Aplicación del sandbox: validar el formato binario (bytes mágicos de ELF/Mach-O/PE) es un filtro rápido y confiable.
Inicio rápido
Instala el SDK
Los SDK oficiales se encargan de toda la configuración del servidor gRPC, el manejo de señales y el puente de protocolos. Tú solo implementas las interfaces de los handlers.
Go (recomendado):
go get github.com/neboloop/nebo-sdk-go Rust (próximamente):
# Coming soon
[dependencies]
nebo-sdk = "0.1" C/C++ (próximamente):
# Coming soon — Add as a CMake subdirectory or copy headers from sdk/c/include/ Estructura del directorio de la app
Las apps viven en el subdirectorio apps/ de tu directorio de datos de Nebo:
~/Library/Application Support/Nebo/apps/ # macOS
~/.config/nebo/apps/ # Linux
%AppData%\Nebo\apps\ # Windows
apps/
com.example.myapp/
manifest.json # Required: app metadata
binary # Required: executable (or named "app")
signatures.json # Required for NeboAI distribution, optional in dev
TOOL.md # Required: tool instructions for the agent
data/ # Auto-created: app's sandboxed storage
logs/ # Auto-created: stdout.log, stderr.log
ui/ # Optional: static UI assets (HTML/CSS/JS) Lista mínima para una app
- Crea
manifest.jsonconid,name,versionyprovides - Escribe
TOOL.mddescribiendo cómo debe usar tu herramienta el empleado de IA - Instala el SDK (
go get github.com/neboloop/nebo-sdk-go) - Implementa la interfaz del handler para tu capacidad (
ToolHandler,ChannelHandler, etc.) - Registra el handler y llama a
app.Run() - Compila un binario nativo (
go build -o binary .) - Coloca el binario + manifest.json + TOOL.md en el directorio
apps/<your-app-id>/ - Nebo lo detecta y lo inicia automáticamente
Configuración
manifest.json
Toda app requiere un manifest.json:
{
"id": "com.example.myapp",
"name": "My App",
"version": "1.0.0",
"description": "What this app does",
"runtime": "local",
"protocol": "grpc",
"provides": ["tool:my_tool"],
"permissions": ["network:outbound"],
"settings": [
{
"key": "api_key",
"title": "API Key",
"type": "password",
"required": true,
"description": "Your API key for the service",
"secret": true
}
]
} Campos obligatorios:
| Campo | Descripción |
|---|---|
id | Identificador en dominio inverso (por ejemplo, com.mycompany.myapp) |
name | Nombre legible |
version | Cadena semver |
provides | Al menos una capacidad (ver abajo) |
Campos opcionales:
| Campo | Valor predeterminado | Descripción |
|---|---|---|
runtime | "local" | "local" o "remote" |
protocol | "grpc" | Solo se admite "grpc" |
permissions | [] | A qué necesita acceder la app |
description | "" | Se muestra en la interfaz |
settings | [] | Opciones configurables (se muestran en la interfaz de Configuración) |
oauth | [] | Requisitos del proveedor de OAuth (ver la sección de OAuth más abajo) |
Capacidades
Declara lo que ofrece tu app:
| Capacidad | Servicio gRPC | Descripción |
|---|---|---|
gateway | GatewayService | Enrutamiento de modelos LLM |
tool:<name> | ToolService | Una herramienta con nombre para el empleado de IA |
channel:<name> | ChannelService | Un canal de mensajería |
comm | CommService | Comunicación entre empleados de IA |
ui | UIService | Interfaz personalizada con proxy HTTP |
schedule | ScheduleService | Programación personalizada |
vision | ToolService | Procesamiento de visión |
browser | ToolService | Automatización del navegador |
Una app puede ofrecer varias capacidades. Por ejemplo, una app podría ofrecer una herramienta y también un panel de interfaz.
Permisos
Los permisos controlan a qué puede acceder la app. Todo está denegado por defecto: si no se declara, la app no puede usarlo.
| Prefijo | Ejemplos | Descripción |
|---|---|---|
network: | network:outbound, network:* | Acceso a la red |
filesystem: | filesystem:read, filesystem:write | Acceso al sistema de archivos |
memory: | memory:read, memory:write | Acceso a la memoria del empleado de IA |
session: | session:read | Sesiones de conversación |
tool: | tool:shell, tool:file | Usar otras herramientas |
shell: | shell:exec | Ejecución de comandos de shell |
channel: | channel:send, channel:* | Operaciones de canal |
comm: | comm:send, comm:* | Comunicación entre empleados de IA |
model: | model:chat | Acceso a modelos de IA |
user: | user:token | Recibir el JWT del usuario en las solicitudes |
schedule: | schedule:create | Gestión de tareas cron |
database: | database:query | Acceso a la base de datos |
storage: | storage:read, storage:write | Almacenamiento persistente |
context: | context:read | Acceso al contexto del empleado de IA |
subagent: | subagent:spawn | Operaciones de subagentes |
lane: | lane:enqueue | Operaciones de carriles |
notification: | notification:send | Notificaciones push |
embedding: | embedding:search | Acceso a embeddings vectoriales |
skill: | skill:invoke | Invocación de skills |
advisor: | advisor:consult | Acceso al sistema de asesores |
mcp: | mcp:connect | Acceso a servidores MCP |
voice: | voice:record | Acceso a voz y audio |
browser: | browser:navigate | Automatización del navegador |
oauth: | oauth:google, oauth:* | Acceso a tokens de OAuth |
settings: | settings:read | Acceso a la configuración |
capability: | capability:register | Registro de capacidades |
Se admiten permisos comodín: network:* coincide con cualquier verificación de permiso network:.
Configuración
Las opciones aparecen en la interfaz de Nebo, en el panel de configuración de la app. Nebo las guarda en la base de datos y se las envía a tu app mediante el RPC Configure cuando cambian.
El esquema de configuración se incluye en la ficha de tu app en la tienda de NeboAI. Las apps con opciones obligatorias sin configurar muestran la insignia "Needs Setup" en la interfaz.
| Tipo | Descripción |
|---|---|
text | Campo de texto de una línea |
password | Campo de texto oculto |
toggle | Interruptor booleano de encendido/apagado |
select | Menú desplegable con opciones predefinidas |
number | Campo numérico |
url | Campo de URL con validación |
{
"key": "region",
"title": "Region",
"type": "select",
"required": true,
"default": "us-east-1",
"options": [
{"label": "US East", "value": "us-east-1"},
{"label": "EU West", "value": "eu-west-1"}
]
} Requisitos de OAuth
Las apps pueden declarar requisitos de proveedores de OAuth. El intermediario de OAuth de Nebo se encarga de todo el flujo: las apps reciben los tokens automáticamente mediante el RPC Configure.
{
"oauth": [
{
"provider": "google",
"scopes": ["https://www.googleapis.com/auth/calendar"]
}
]
} | Campo | Descripción |
|---|---|
provider | Proveedor de OAuth: "google", "microsoft", "github" |
scopes | Arreglo de los alcances de OAuth que necesita la app |
Cuando el usuario instala la app, Nebo le pide que autorice los alcances de OAuth requeridos. La app recibe los tokens renovados mediante el RPC Configure sin tener que manejar el flujo de OAuth por su cuenta.
Variables de entorno
El proceso de tu app recibe un entorno depurado. Se eliminan todos los secretos. Recibes:
| Variable | Valor |
|---|---|
NEBO_APP_DIR | Directorio de instalación de la app |
NEBO_APP_SOCK | Ruta del socket Unix que se debe crear |
NEBO_APP_ID | ID de la app según el manifiesto |
NEBO_APP_NAME | Nombre de la app según el manifiesto |
NEBO_APP_VERSION | Versión de la app según el manifiesto |
NEBO_APP_DATA | Ruta al directorio data/ de la app |
PATH | PATH del sistema (se transfiere tal cual) |
HOME | Directorio personal del usuario (se transfiere tal cual) |
TMPDIR | Directorio temporal (se transfiere tal cual) |
Importante: tu binario debe crear un servidor gRPC que escuche en el socket Unix de NEBO_APP_SOCK. Nebo espera hasta 10 segundos a que aparezca este socket.
Secuencia de inicio de la app
- Nebo lee
manifest.jsony lo valida - Busca el ejecutable
binaryoappen el directorio de la app - Comprueba si existe el marcador
.quarantined(no inicia apps en cuarentena) - Verificación de revocación (solo apps distribuidas por NeboAI)
- Verificación de firma (solo apps distribuidas por NeboAI; se omite en desarrollo)
- Validación del binario (rechaza enlaces simbólicos, scripts, archivos no ejecutables y archivos demasiado grandes)
- Limpia el socket obsoleto de la ejecución anterior
- Crea el directorio
data/para el almacenamiento aislado - Configura archivos de registro por app (
logs/stdout.log,logs/stderr.log) - Inicia el binario con un entorno depurado y aislamiento del grupo de procesos
- Espera a que aparezca el socket Unix (retroceso exponencial, máximo 10 segundos)
- Se conecta por gRPC a través del socket Unix
- Crea clientes gRPC específicos para cada capacidad según
provides - Ejecuta una verificación de estado
- Registra las capacidades con el empleado de IA (herramientas, gateway, comm, etc.)
Apps de herramientas
Declara "provides": ["tool:my_tool_name"] en tu manifiesto.
El patrón STRAP
Todas las apps de herramientas de Nebo deben usar el STRAP (Single Tool Resource Action Pattern) para su esquema y el enrutamiento de la ejecución. Es el mismo patrón que Nebo usa internamente para consolidar más de 35 herramientas individuales en 4 herramientas de dominio, lo que reduce la carga de contexto del LLM en ~80 %.
Idea central: en lugar de registrar varias herramientas (get_events, check_availability, suggest_slots), registra UNA sola herramienta con campos action (y, si quieres, resource) que enrutan al handler correcto.
Ejemplo de un solo recurso (calendario):
calendar(action: "get_events", start: "2025-01-15T09:00:00Z", end: "2025-01-16T00:00:00Z")
calendar(action: "next_event")
calendar(action: "check_availability", start: "...", end: "...")
calendar(action: "suggest_slots", duration_minutes: 30, preferred_time: "morning") Ejemplo de varios recursos (gestor de proyectos):
project(resource: "task", action: "create", title: "Ship v2", assignee: "alice")
project(resource: "task", action: "list", status: "open")
project(resource: "milestone", action: "create", name: "Beta", deadline: "2025-03-01")
project(resource: "milestone", action: "list") Reglas del esquema:
- Incluye siempre un campo
actioncomo enum de cadena obligatorio - Agrega un campo
resource(enum de cadena obligatorio) solo si tu herramienta gestiona varios tipos de recursos distintos - Todos los demás campos son parámetros específicos de cada acción
- La descripción del enum
actiondebe enumerar todas las acciones disponibles
Por qué importa STRAP:
- Los LLM aprenden una sola vez el patrón de enrutamiento por
actiony lo generalizan a todas las operaciones - Las definiciones de herramientas consumen ~6 % del contexto; STRAP lo reduce en un 80 %
- Las nuevas operaciones son solo valores nuevos en el enum, no registros de herramientas nuevas
- Funciona igual con modelos alojados y locales
Ejemplo en Go — Herramienta de calculadora
package main
import (
"context"
"encoding/json"
"fmt"
"log"
nebo "github.com/neboloop/nebo-sdk-go"
)
type Calculator struct{}
func (c *Calculator) Name() string { return "calculator" }
func (c *Calculator) Description() string { return "Performs arithmetic calculations." }
func (c *Calculator) Schema() json.RawMessage {
return nebo.NewSchema("add", "subtract", "multiply", "divide").
Number("a", "First operand", true).
Number("b", "Second operand", true).
Build()
}
func (c *Calculator) Execute(_ context.Context, input json.RawMessage) (string, error) {
var in struct {
Action string `json:"action"`
A float64 `json:"a"`
B float64 `json:"b"`
}
if err := json.Unmarshal(input, &in); err != nil {
return "", fmt.Errorf("invalid input: %w", err)
}
var result float64
switch in.Action {
case "add":
result = in.A + in.B
case "subtract":
result = in.A - in.B
case "multiply":
result = in.A * in.B
case "divide":
if in.B == 0 {
return "", fmt.Errorf("division by zero")
}
result = in.A / in.B
default:
return "", fmt.Errorf("unknown action: %s", in.Action)
}
return fmt.Sprintf("%g %s %g = %g", in.A, in.Action, in.B, result), nil
}
func main() {
app, err := nebo.New()
if err != nil {
log.Fatal(err)
}
app.RegisterTool(&Calculator{})
log.Fatal(app.Run())
} manifest.json:
{
"id": "com.example.calculator",
"name": "Calculator",
"version": "1.0.0",
"description": "Arithmetic calculator tool for the agent",
"runtime": "local",
"protocol": "grpc",
"provides": ["tool:calculator"],
"permissions": []
} Compila e instala:
go build -o binary .
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.calculator
cp binary manifest.json ~/Library/Application\ Support/Nebo/apps/com.example.calculator/ Ejemplo en Rust
use async_trait::async_trait;
use nebo_sdk::{NeboApp, NeboError, SchemaBuilder};
use nebo_sdk::tool::ToolHandler;
use serde::Deserialize;
use serde_json::Value;
struct Calculator;
#[derive(Deserialize)]
struct Input { action: String, a: f64, b: f64 }
#[async_trait]
impl ToolHandler for Calculator {
fn name(&self) -> &str { "calculator" }
fn description(&self) -> &str { "Performs arithmetic calculations." }
fn schema(&self) -> Value {
SchemaBuilder::new(&["add", "subtract", "multiply", "divide"])
.number("a", "First operand", true)
.number("b", "Second operand", true)
.build()
}
async fn execute(&self, input: Value) -> Result<String, NeboError> {
let i: Input = serde_json::from_value(input)
.map_err(|e| NeboError::Execution(e.to_string()))?;
let r = match i.action.as_str() {
"add" => i.a + i.b,
"subtract" => i.a - i.b,
"multiply" => i.a * i.b,
"divide" => {
if i.b == 0.0 {
return Err(NeboError::Execution("division by zero".into()));
}
i.a / i.b
}
other => return Err(NeboError::Execution(format!("unknown action: {other}"))),
};
Ok(format!("{} {} {} = {}", i.a, i.action, i.b, r))
}
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
NeboApp::new()?.register_tool(Calculator).run().await?;
Ok(())
} Ejemplo en C
#include <nebo/nebo.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static int calculator_execute(const char *input_json, char **output, int *is_error) {
/* Parse JSON, compute result, set *output */
*output = strdup("2 add 3 = 5");
*is_error = 0;
return 0;
}
int main(void) {
const char *actions[] = {"add", "subtract", "multiply", "divide", NULL};
nebo_schema_builder_t *sb = nebo_schema_new(actions);
nebo_schema_number(sb, "a", "First operand", 1);
nebo_schema_number(sb, "b", "Second operand", 1);
char *schema = nebo_schema_build(sb);
nebo_schema_free(sb);
nebo_tool_handler_t calculator = {
.name = "calculator",
.description = "Performs arithmetic calculations.",
.schema = schema,
.execute = calculator_execute,
};
nebo_app_t *app = nebo_app_new();
nebo_app_register_tool(app, &calculator);
int ret = nebo_app_run(app);
free(schema);
return ret;
} Apps de canal
Declara "provides": ["channel:my_channel"] y "permissions": ["channel:send"].
Las apps de canal conectan plataformas de mensajería externas (Telegram, Discord, Slack, etc.) con el empleado de IA de Nebo. Cuando un usuario envía un mensaje en la plataforma externa, tu app se lo transmite a Nebo mediante Receive. Cuando el empleado de IA quiere responder, Nebo llama al Send de tu app.
Cómo funciona
- Nebo llama a
ID()para obtener el identificador único de tu canal - Nebo llama a
Connect()con la configuración de las opciones de tu app - Nebo abre un flujo
Receive(): tu app envía los mensajes entrantes cada vez que un usuario le escribe al bot - Los mensajes entrantes se enrutan al carril de conversación principal del empleado de IA
- Cuando el empleado de IA quiere enviar un mensaje, Nebo llama a
Send()con el sobre de mensaje v1 - Al apagarse, Nebo llama a
Disconnect()
Sobre de mensaje v1
Todos los mensajes de canal, entrantes y salientes, usan el sobre de mensaje común:
{
"message_id": "01953f8a-...",
"channel_id": "telegram:12345",
"sender": { "name": "Alex", "role": "COO", "bot_id": "uuid" },
"text": "Q3 numbers look good...",
"attachments": [{ "type": "image", "url": "https://...", "filename": "chart.png", "size": 45000 }],
"reply_to": "01953f89-...",
"actions": [{ "label": "Approve", "callback_id": "approve_q3" }],
"platform_data": null,
"timestamp": "2026-02-12T15:10:00Z"
} | Campo | Tipo | Descripción |
|---|---|---|
message_id | UUID v7 | ID único ordenado por tiempo |
channel_id | {type}:{platform_id} | Identificador de canal enrutable |
sender | object | Identidad del bot: nombre, rol, botId |
text | string | Cuerpo del mensaje |
attachments | array | Archivos, imágenes, audio |
reply_to | UUID v7 | ID del mensaje padre para los hilos |
actions | array | Botones y teclados interactivos |
platform_data | bytes | Datos opacos que se transfieren tal cual para funciones propias de cada plataforma |
timestamp | ISO 8601 | Lo define el publicador |
Diseño en dos capas: los campos comunes (text, attachments, reply_to, actions) cubren el 90 % de los mensajes que inician los empleados. Las funciones propias de cada plataforma van en platform_data: tu plugin las convierte desde y hacia el formato nativo de la plataforma.
Flujos de conversación
Los mensajes de canal se enrutan por flujos de conversación separados para cada canal, para mantenerlos aislados:
neboai/bot/{botID}/channels/{channelType}/inbound # messages from users → agent
neboai/bot/{botID}/channels/{channelType}/outbound # messages from agent → channel Ejemplo en Go — Canal de Telegram
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"time"
"github.com/google/uuid"
tgbot "github.com/go-telegram/bot"
nebo "github.com/neboloop/nebo-sdk-go"
)
type Telegram struct {
bot *tgbot.Bot
messages chan nebo.ChannelEnvelope
cancel context.CancelFunc
}
func (t *Telegram) ID() string { return "telegram" }
func (t *Telegram) Connect(_ context.Context, config map[string]string) error {
token := config["bot_token"]
if token == "" {
return fmt.Errorf("bot_token is required")
}
botCtx, cancel := context.WithCancel(context.Background())
t.cancel = cancel
bot, err := tgbot.New(token, tgbot.WithDefaultHandler(
func(bCtx context.Context, b *tgbot.Bot, update *tgbot.Update) {
if update.Message == nil {
return
}
env := nebo.ChannelEnvelope{
MessageID: uuid.Must(uuid.NewV7()).String(),
ChannelID: fmt.Sprintf("telegram:%d", update.Message.Chat.ID),
Text: update.Message.Text,
Timestamp: time.Unix(int64(update.Message.Date), 0).UTC(),
}
t.messages <- env
},
))
if err != nil {
return err
}
t.bot = bot
go bot.Start(botCtx)
return nil
}
func (t *Telegram) Send(ctx context.Context, env nebo.ChannelEnvelope) (string, error) {
if t.bot == nil {
return "", fmt.Errorf("not connected")
}
chatID := env.ChannelID[len("telegram:"):]
params := &tgbot.SendMessageParams{
ChatID: chatID,
Text: env.Text,
}
msg, err := t.bot.SendMessage(ctx, params)
if err != nil {
return "", err
}
return fmt.Sprintf("%d", msg.MessageID), nil
}
func (t *Telegram) Receive(_ context.Context) (<-chan nebo.ChannelEnvelope, error) {
return t.messages, nil
}
func (t *Telegram) Disconnect(_ context.Context) error {
if t.cancel != nil {
t.cancel()
}
return nil
}
func main() {
app, err := nebo.New()
if err != nil {
log.Fatal(err)
}
app.RegisterChannel(&Telegram{
messages: make(chan nebo.ChannelEnvelope, 100),
})
log.Fatal(app.Run())
} manifest.json:
{
"id": "com.example.telegram",
"name": "Telegram",
"version": "1.0.0",
"description": "Telegram messaging channel for Nebo",
"runtime": "local",
"protocol": "grpc",
"provides": ["channel:telegram"],
"permissions": ["channel:send", "network:outbound"],
"settings": [
{
"key": "bot_token",
"title": "Bot Token",
"type": "password",
"required": true,
"description": "Telegram bot token from @BotFather",
"secret": true
}
]
} Más capacidades
App de comunicación
Declara "provides": ["comm"] y "permissions": ["comm:*"]. Las apps de comunicación permiten que los empleados de IA se comuniquen entre sí.
| Campo | Descripción |
|---|---|
from | ID del empleado que envía |
to | ID del empleado que recibe |
topic | Tema o canal del mensaje |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Cuerpo del mensaje |
Comportamientos clave:
Registeranuncia a este empleado de IA en la red junto con sus capacidadesSubscribe/Unsubscribegestionan las suscripciones a temasReceivetransmite los mensajes entrantes (streaming del servidor, igual que en los canales)- Solo puede haber una app de comunicación activa a la vez
App de gateway
Una app de gateway enruta las solicitudes al LLM hacia los modelos. Declara "provides": ["gateway"] y "permissions": ["network:outbound", "user:token"].
GatewayRequest contiene mensajes, herramientas, prompt del sistema, máximo de tokens, temperatura y un UserContext (token JWT si se concede el permiso user:token).
Tipos de GatewayEvent:
| Tipo | Contenido | Descripción |
|---|---|---|
"text" | Fragmento de texto | Token de texto en streaming |
"tool_call" | JSON | El modelo quiere llamar a una herramienta |
"thinking" | Fragmento de texto | Razonamiento extendido |
"error" | Mensaje de error | Algo salió mal |
"done" | Vacío | El flujo terminó |
App de interfaz
Una app de interfaz ofrece una interfaz de configuración personalizada que se abre en la ventana del navegador integrado de Nebo. Declara "provides": ["ui"]. A diferencia del formulario de configuración automático (que Nebo dibuja a partir de tu manifiesto settings), una app de interfaz sirve su propio frontend completo en HTML/CSS/JS.
Tu app incluye un directorio ui/ con recursos web estáticos (HTML, CSS, JS; normalmente una SPA con index.html). Nebo sirve estos archivos directamente y redirige las llamadas a la API hacia tu app mediante gRPC.
| Ruta | Mecanismo | Propósito |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Servidor de archivos estáticos | Sirve archivos de tu directorio ui/ (con respaldo de SPA a index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Redirige las solicitudes HTTP al UIService.HandleRequest() de tu app |
El SDK envuelve un net/http.ServeMux estándar, así que escribes handlers HTTP normales de Go; el SDK se encarga automáticamente del puente con gRPC.
Ejemplo en Go — Interfaz de panel:
package main
import (
"encoding/json"
"log"
"net/http"
nebo "github.com/neboloop/nebo-sdk-go"
)
type Dashboard struct {
mux *http.ServeMux
}
func NewDashboard() *Dashboard {
d := &Dashboard{mux: http.NewServeMux()}
d.mux.HandleFunc("GET /status", func(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
})
d.mux.HandleFunc("POST /action", func(w http.ResponseWriter, r *http.Request) {
var req map[string]string
json.NewDecoder(r.Body).Decode(&req)
json.NewEncoder(w).Encode(map[string]string{"result": "done"})
})
return d
}
func (d *Dashboard) Handler() *http.ServeMux { return d.mux }
func main() {
app, err := nebo.New()
if err != nil {
log.Fatal(err)
}
app.RegisterUI(NewDashboard())
log.Fatal(app.Run())
} Tu ui/index.html haría llamadas fetch a /api/v1/apps/com.example.dashboard/api/status, que se redirigen a tu handler mux.
App de programación
Una app de programación reemplaza el programador cron integrado de Nebo. Declara "provides": ["schedule"] y "permissions": ["schedule:create"].
Cuando se inicia tu app de programación, Nebo enruta toda la programación a través de tu app en lugar del motor cron predeterminado. Si tu app falla, Nebo vuelve automáticamente al motor integrado.
- Tu app es dueña del estado de las programaciones: Nebo no guarda programaciones en su propia base de datos mientras haya una app de programación activa
- CRUD estándar:
Create,Get,List,Update,Delete,Enable,Disable Triggerses un RPC con streaming del servidor: tu app envía un mensaje de disparo cada vez que se ejecuta una programación- Solo puede haber una app de programación activa a la vez
Apps con varias capacidades
Una app puede ofrecer varias capacidades. Por ejemplo, una app de panel con una herramienta y una interfaz:
{
"id": "com.example.dashboard",
"name": "Dashboard",
"version": "1.0.0",
"provides": ["tool:dashboard_query", "ui"],
"permissions": ["network:outbound"]
} app, _ := nebo.New()
app.RegisterTool(&dashboardTool{})
app.RegisterUI(&dashboardUI{})
log.Fatal(app.Run()) Empaquetado
Formato .napp
Para distribuirla a través de NeboAI, empaqueta tu app como un archivo .napp (un archivo tar.gz):
cd com.example.myapp/
tar -czf myapp-1.0.0.napp manifest.json binary signatures.json TOOL.md Archivos obligatorios:
| Archivo | Tamaño máximo | Descripción |
|---|---|---|
manifest.json | 1 MB | Metadatos de la app |
binary o app | 500 MB | Ejecutable |
signatures.json | 1 MB | Firmas Ed25519 |
TOOL.md | 1 MB | Instrucciones de la herramienta para el empleado de IA |
Reglas de seguridad durante la extracción:
- Nada de recorrido de rutas (se rechaza
../) - Nada de enlaces simbólicos (se rechazan)
- Nada de rutas absolutas (se rechazan)
- Solo se aceptan nombres de archivo de la lista permitida
Firmas
NeboAI firma las apps con Ed25519. El formato de signatures.json:
{
"key_id": "a1b2c3d4",
"algorithm": "ed25519",
"manifest_signature": "<base64 signature of raw manifest.json bytes>",
"binary_sha256": "<hex SHA256 of binary>",
"binary_signature": "<base64 signature of raw binary bytes>"
} En modo de desarrollo (sin una URL de NeboAI configurada), la verificación de firmas se omite por completo. No necesitas signatures.json para el desarrollo local.
Publicación
Cuando tu app funcione localmente, publícala a través de NeboAI para distribuirla a todos los usuarios de Nebo.
Configuración de la cuenta de desarrollador
- Registra una cuenta de NeboAI en
POST /api/v1/owners/register - Inicia sesión para obtener un token JWT:
POST /api/v1/owners/login - Crea una cuenta de desarrollador:
POST /api/v1/developer/accounts
Flujo de envío
draft → pending_review → [approved] → published
→ [rejected] → draft (fix and resubmit) Paso 1: Crea la app
curl -X POST https://neboai.com/api/v1/developer/apps \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My App",
"version": "1.0.0",
"description": "What it does",
"category": "productivity",
"visibility": "public"
}' Paso 2: Sube los binarios de cada plataforma
curl -X POST https://neboai.com/api/v1/developer/apps/{id}/binaries \
-H "Authorization: Bearer $TOKEN" \
-F "binary=@myapp-darwin-arm64" \
-F "platform=darwin-arm64" Sube un binario por plataforma: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.
Paso 3: Envíala a revisión
curl -X POST https://neboai.com/api/v1/developer/apps/{id}/submit \
-H "Authorization: Bearer $TOKEN" Proceso de revisión
- Análisis automático: los binarios se analizan con VirusTotal
- Revisión administrativa: el equipo de NeboAI revisa los metadatos, el manifiesto y los resultados del análisis
- Si se aprueba: NeboAI firma la app con Ed25519 y la publica
- Si se rechaza: recibes el motivo y puedes corregirla y volver a enviarla
Tiempo de revisión objetivo: <24 horas.
Publicar actualizaciones
- Actualiza la versión de la app:
PUT /api/v1/developer/apps/{id}con la nueva versión - Sube binarios nuevos para cada plataforma
- Vuelve a enviarla a revisión
Cada actualización pasa por el mismo proceso de revisión. Las versiones anteriores siguen disponibles hasta que se aprueba la nueva.
Metadatos de la tienda
| Campo | Descripción |
|---|---|
category | p. ej., productividad, comunicación, herramientas para desarrolladores |
icon | URL del ícono de la app |
visibility | public o private |
description | Puede ser más larga y detallada que la descripción del manifiesto |
Flujo de desarrollo
Desarrollo local
No hace falta empaquetar para el desarrollo local:
- Crea el directorio de tu app:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Escribe tu
manifest.jsony tu código - Compila tu binario:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo detecta automáticamente el nuevo directorio (o reinicia Nebo)
- Después de cambiar el código, vuelve a compilar el binario; el observador de archivos reiniciará la app
Ver los registros
La salida stdout/stderr de la app se guarda en archivos de registro por app:
tail -f ~/Library/Application\ Support/Nebo/apps/com.example.myapp/logs/stdout.log
tail -f ~/Library/Application\ Support/Nebo/apps/com.example.myapp/logs/stderr.log Datos persistentes
Usa el directorio data/ (también disponible como la variable de entorno NEBO_APP_DATA) para cualquier archivo que tu app necesite conservar. Este directorio se mantiene tras las actualizaciones de la app y la cuarentena.
Consejos de depuración
- Si tu app no inicia, revisa
logs/stderr.logpara ver los errores - Asegúrate de que el binario sea ejecutable (
chmod +x binary) - Asegúrate de estar escuchando en la ruta del socket Unix de
NEBO_APP_SOCK - El socket debe estar listo dentro de los 10 segundos posteriores al inicio
- Usa
NEBO_APP_DATApara el almacenamiento, no rutas fijas en el código - Escribe en stderr para los registros de depuración (se guardan en
logs/stderr.log)
Verificación
# List installed apps
nebo apps list
# Check running apps via the web UI Settings > Apps
# Or check the apps directory for running sockets
ls ~/Library/Application\ Support/Nebo/apps/*/app.sock Desinstalación
nebo apps uninstall com.example.myapp Skills
Qué son las skills
Las skills son conjuntos de instrucciones que definen cómo se comporta Nebo durante una conversación. Cuando una skill está activa, su contenido se inserta directamente en el prompt del sistema y orienta el tono, la metodología, el conocimiento especializado y el uso de herramientas del empleado de IA en esa sesión.
Las skills no son código. Son documentos Markdown con metadatos YAML. Sin compilación, sin binario, sin gRPC. Una skill es un archivo SKILL.md dentro de un directorio. Eso es todo.
Las skills son contextuales y temporales. Se activan cuando son relevantes (por coincidencia de disparadores o carga manual), duran unos cuantos turnos y vencen cuando ya no se necesitan. Así el contexto del empleado de IA se mantiene liviano: en el prompt solo está la guía que importa en ese momento.
Las skills complementan a las apps. Las apps ofrecen capacidades ejecutables (herramientas, canales, gateways). Las skills ofrecen una guía de orquestación: cómo usar bien esas herramientas. Una app de calendario le da a Nebo la capacidad de leer y escribir eventos. Una skill de "preparar reuniones" le dice a Nebo cómo prepararse para las reuniones usando esa app de calendario, el correo y la búsqueda web en conjunto.
Skills vs. apps
| Skills | Apps | |
|---|---|---|
| Formato | Markdown (SKILL.md) | Binario compilado (.napp) |
| Ejecución | Se inserta en el prompt del sistema | Proceso aislado en sandbox mediante gRPC |
| Ofrece | Guía de comportamiento, metodología | Herramientas, canales, paneles de interfaz |
| Duración | Limitada a la sesión, vence por TTL | Siempre en ejecución |
| Creación | Escribir un archivo Markdown | Escribir, compilar, firmar, empaquetar |
| Seguridad | No requiere permisos | Sandbox con todo denegado por defecto |
Inicio rápido
Crea un directorio en tu carpeta de skills de Nebo con un archivo SKILL.md:
~/Library/Application Support/Nebo/skills/ # macOS
~/.config/nebo/skills/ # Linux
%AppData%\Nebo\skills\ # Windows mkdir -p ~/.config/nebo/skills/my-skill Escribe un SKILL.md:
---
name: my-skill
description: One-line description of what this skill does
version: "1.0.0"
triggers:
- keyword that activates this skill
- another trigger phrase
---
# My Skill
Instructions for Nebo when this skill is active.
Tell the agent what to do, how to approach problems,
what tools to use, and what tone to take. Nebo vigila el directorio de skills con fsnotify. Tu skill está disponible al instante, sin necesidad de reiniciar. Di algo que coincida con un disparador y se activará automáticamente.
O pídeselo directamente a Nebo: "Crea una skill para escribir entradas de blog", y Nebo escribirá el archivo SKILL.md por ti.
Formato de SKILL.md
Cada skill es un único archivo SKILL.md con dos partes: el frontmatter YAML entre marcadores --- y un cuerpo en Markdown (las instrucciones que se insertan en el prompt del sistema).
| Campo | Obligatorio | Valor predeterminado | Descripción |
|---|---|---|---|
name | Sí | — | Identificador único (se convierte en el slug) |
description | Sí | — | Descripción de una línea que se muestra en el catálogo de skills |
version | No | "1.0.0" | Semver para seguir las actualizaciones |
author | No | — | Autor de la skill |
priority | No | 0 | Mayor = se evalúa primero (100+ para anulaciones críticas) |
max_turns | No | 4 | Turnos de inactividad antes de que venza automáticamente |
triggers | No | [] | Frases que activan automáticamente esta skill (coincidencia de subcadena sin distinguir mayúsculas) |
tools | No | [] | Herramientas que esta skill espera usar (informativo) |
dependencies | No | [] | Otras skills que deben estar instaladas |
tags | No | [] | Para clasificar y descubrir |
platform | No | [] | Plataformas compatibles: macos, linux, windows (vacío = todas) |
Cómo se activan las skills
Las skills siguen un modelo de activación en dos fases: primero una sugerencia, luego la invocación.
Fase 1: Coincidencia de disparadores. Cada vez que un usuario envía un mensaje, Nebo revisa todas las skills registradas en busca de disparadores que coincidan. Las skills que coinciden aparecen como sugerencias en el prompt del sistema. El empleado de IA ve la sugerencia y decide si invoca la skill.
Fase 2: Invocación. El empleado de IA invoca una skill con esta llamada:
skill(name: "code-review") Esto devuelve la plantilla completa de SKILL.md como resultado de la herramienta, registra la invocación y vuelve a insertar la plantilla en el prompt del sistema en los turnos siguientes.
TTL y vencimiento:
- Skills activadas por coincidencia: 4 turnos de inactividad (configurable con
max_turns) - Skills cargadas manualmente: 6 turnos de inactividad
- Volver a invocarla reinicia el contador
- Límite máximo: 4 skills activas por sesión
- Presupuesto de tokens: el contenido combinado de las skills activas tiene un tope de 16,000 caracteres
Gestión de skills
El empleado de IA puede gestionar las skills con la herramienta skill:
| Acción | Descripción | Ejemplo |
|---|---|---|
catalog | Listar todas las skills disponibles | skill(action: "catalog") |
load | Activar para esta sesión | skill(name: "code-review", action: "load") |
unload | Desactivar una skill | skill(name: "code-review", action: "unload") |
create | Crear una skill nueva en el disco | skill(action: "create", content: "...") |
update | Actualizar una skill existente | skill(name: "my-skill", action: "update", content: "...") |
delete | Eliminar una skill del disco | skill(name: "my-skill", action: "delete") |
Cómo escribir buenas skills
Una buena plantilla de skill tiene:
- Un encabezado claro: le dice al empleado de IA en qué modo está
- Principios básicos: las reglas de comportamiento no negociables
- Metodología: un enfoque paso a paso para los escenarios comunes
- Ejemplos: patrones concretos de mensaje del usuario y respuesta
- Antipatrones: lo que NO se debe hacer (los modelos aprenden bien de los ejemplos negativos)
Consejo: cada skill debe hacer bien una sola cosa. No crees una skill de "programación general": crea code-review, debugging y api-design como skills separadas. El empleado de IA puede tener varias activas al mismo tiempo.
Skills incluidas
Nebo incluye skills que cubren casos de uso comunes:
| Skill | Prioridad | Descripción |
|---|---|---|
onboarding | 100 | Bienvenida a nuevos usuarios y recopilación de su perfil |
best-friend | 50 | Skill de personalidad: relajada, leal, sin rodeos |
debugging | 25 | Metodología de depuración sistemática |
api-design | 15 | Buenas prácticas de diseño de API RESTful |
code-review | 10 | Revisión de código estructurada con niveles de gravedad |
database-expert | 10 | Diseño de bases de datos, consultas, optimización |
git-workflow | 10 | Ramas de Git, commits, flujos de PR |
security-audit | 10 | Análisis de seguridad y detección de vulnerabilidades |
Sirven como valores predeterminados útiles y como implementaciones de referencia para crear tus propias skills.
Referencia
Archivos proto
Los archivos proto están en proto/apps/v0/. Los SDK incluyen código pregenerado, así que no necesitas protoc para el desarrollo normal.
| Archivo | Servicio | RPC principales |
|---|---|---|
v0/common.proto | (solo mensajes) | HealthCheckRequest/Response, SettingsMap, UserContext, Empty |
v0/tool.proto | ToolService | Name, Description, Schema, Execute, RequiresApproval, Configure |
v0/channel.proto | ChannelService | ID, Connect, Disconnect, Send, Receive (stream), Configure |
v0/comm.proto | CommService | Name, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (stream), Configure |
v0/gateway.proto | GatewayService | HealthCheck, Stream (stream), Poll, Cancel, Configure |
v0/ui.proto | UIService | HealthCheck, HandleRequest, Configure |
v0/schedule.proto | ScheduleService | HealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (stream), Configure |
Cada servicio incluye los RPC HealthCheck y Configure. El SDK maneja ambos automáticamente.
Tipos proto de canal
| Tipo de mensaje | Descripción |
|---|---|
ChannelSendRequest | Sobre de mensaje saliente con message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID de mensaje de la plataforma para los hilos |
InboundMessage | Sobre de mensaje entrante con todos los campos comunes + timestamp |
MessageSender | Identidad del bot (name, role, botId), completada por el broker |
Attachment | Adjunto de archivo, imagen o audio (type, url, filename, size) |
MessageAction | Acción de botón o teclado interactivo (label, callback_id) |
Identidad y roles del bot
Los bots de Nebo tienen un modelo de identidad de tres ejes:
- creature: qué es el bot (arquetipo): "Estratega ingenioso", "Investigador meticuloso"
- role: cómo se relaciona con el usuario (relación): "Amigo", "COO", "Mentor"
- vibe: su energía (estilo de comunicación): "Tranquilo pero con opiniones", "Cálido y alentador"
Cuando tu plugin de canal recibe un mensaje saliente, el campo sender contiene el name y el role del bot. Úsalos para dar formato al nombre que se muestra en tu plataforma. El rol no es un cargo: describe una relación. "Amigo", "Hijo" y "Mentor" son roles válidos, igual que "COO" y "DevLead".