NeboAI
NeboAI
Comenzar

Crea apps para Nebo

Dale a tu IA nuevos superpoderes. Herramientas, canales, gateways, paneles de interfaz: todo lo que puedas imaginar, compilado como binario nativo.

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.

EstadoLenguajes
CompatiblesGo (recomendado), Rust, C/C++, Zig
RechazadosPython, 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

  1. Crea manifest.json con id, name, version y provides
  2. Escribe TOOL.md describiendo cómo debe usar tu herramienta el empleado de IA
  3. Instala el SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Implementa la interfaz del handler para tu capacidad (ToolHandler, ChannelHandler, etc.)
  5. Registra el handler y llama a app.Run()
  6. Compila un binario nativo (go build -o binary .)
  7. Coloca el binario + manifest.json + TOOL.md en el directorio apps/<your-app-id>/
  8. 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:

CampoDescripción
idIdentificador en dominio inverso (por ejemplo, com.mycompany.myapp)
nameNombre legible
versionCadena semver
providesAl menos una capacidad (ver abajo)

Campos opcionales:

CampoValor predeterminadoDescripció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:

CapacidadServicio gRPCDescripción
gatewayGatewayServiceEnrutamiento de modelos LLM
tool:<name>ToolServiceUna herramienta con nombre para el empleado de IA
channel:<name>ChannelServiceUn canal de mensajería
commCommServiceComunicación entre empleados de IA
uiUIServiceInterfaz personalizada con proxy HTTP
scheduleScheduleServiceProgramación personalizada
visionToolServiceProcesamiento de visión
browserToolServiceAutomatizació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.

PrefijoEjemplosDescripción
network:network:outbound, network:*Acceso a la red
filesystem:filesystem:read, filesystem:writeAcceso al sistema de archivos
memory:memory:read, memory:writeAcceso a la memoria del empleado de IA
session:session:readSesiones de conversación
tool:tool:shell, tool:fileUsar otras herramientas
shell:shell:execEjecución de comandos de shell
channel:channel:send, channel:*Operaciones de canal
comm:comm:send, comm:*Comunicación entre empleados de IA
model:model:chatAcceso a modelos de IA
user:user:tokenRecibir el JWT del usuario en las solicitudes
schedule:schedule:createGestión de tareas cron
database:database:queryAcceso a la base de datos
storage:storage:read, storage:writeAlmacenamiento persistente
context:context:readAcceso al contexto del empleado de IA
subagent:subagent:spawnOperaciones de subagentes
lane:lane:enqueueOperaciones de carriles
notification:notification:sendNotificaciones push
embedding:embedding:searchAcceso a embeddings vectoriales
skill:skill:invokeInvocación de skills
advisor:advisor:consultAcceso al sistema de asesores
mcp:mcp:connectAcceso a servidores MCP
voice:voice:recordAcceso a voz y audio
browser:browser:navigateAutomatización del navegador
oauth:oauth:google, oauth:*Acceso a tokens de OAuth
settings:settings:readAcceso a la configuración
capability:capability:registerRegistro 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.

TipoDescripción
textCampo de texto de una línea
passwordCampo de texto oculto
toggleInterruptor booleano de encendido/apagado
selectMenú desplegable con opciones predefinidas
numberCampo numérico
urlCampo 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"]
        }
    ]
}
CampoDescripción
providerProveedor de OAuth: "google", "microsoft", "github"
scopesArreglo 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:

VariableValor
NEBO_APP_DIRDirectorio de instalación de la app
NEBO_APP_SOCKRuta del socket Unix que se debe crear
NEBO_APP_IDID de la app según el manifiesto
NEBO_APP_NAMENombre de la app según el manifiesto
NEBO_APP_VERSIONVersión de la app según el manifiesto
NEBO_APP_DATARuta al directorio data/ de la app
PATHPATH del sistema (se transfiere tal cual)
HOMEDirectorio personal del usuario (se transfiere tal cual)
TMPDIRDirectorio 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

  1. Nebo lee manifest.json y lo valida
  2. Busca el ejecutable binary o app en el directorio de la app
  3. Comprueba si existe el marcador .quarantined (no inicia apps en cuarentena)
  4. Verificación de revocación (solo apps distribuidas por NeboAI)
  5. Verificación de firma (solo apps distribuidas por NeboAI; se omite en desarrollo)
  6. Validación del binario (rechaza enlaces simbólicos, scripts, archivos no ejecutables y archivos demasiado grandes)
  7. Limpia el socket obsoleto de la ejecución anterior
  8. Crea el directorio data/ para el almacenamiento aislado
  9. Configura archivos de registro por app (logs/stdout.log, logs/stderr.log)
  10. Inicia el binario con un entorno depurado y aislamiento del grupo de procesos
  11. Espera a que aparezca el socket Unix (retroceso exponencial, máximo 10 segundos)
  12. Se conecta por gRPC a través del socket Unix
  13. Crea clientes gRPC específicos para cada capacidad según provides
  14. Ejecuta una verificación de estado
  15. 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:

  1. Incluye siempre un campo action como enum de cadena obligatorio
  2. Agrega un campo resource (enum de cadena obligatorio) solo si tu herramienta gestiona varios tipos de recursos distintos
  3. Todos los demás campos son parámetros específicos de cada acción
  4. La descripción del enum action debe enumerar todas las acciones disponibles

Por qué importa STRAP:

  • Los LLM aprenden una sola vez el patrón de enrutamiento por action y 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

  1. Nebo llama a ID() para obtener el identificador único de tu canal
  2. Nebo llama a Connect() con la configuración de las opciones de tu app
  3. Nebo abre un flujo Receive(): tu app envía los mensajes entrantes cada vez que un usuario le escribe al bot
  4. Los mensajes entrantes se enrutan al carril de conversación principal del empleado de IA
  5. Cuando el empleado de IA quiere enviar un mensaje, Nebo llama a Send() con el sobre de mensaje v1
  6. 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"
}
CampoTipoDescripción
message_idUUID v7ID único ordenado por tiempo
channel_id{type}:{platform_id}Identificador de canal enrutable
senderobjectIdentidad del bot: nombre, rol, botId
textstringCuerpo del mensaje
attachmentsarrayArchivos, imágenes, audio
reply_toUUID v7ID del mensaje padre para los hilos
actionsarrayBotones y teclados interactivos
platform_databytesDatos opacos que se transfieren tal cual para funciones propias de cada plataforma
timestampISO 8601Lo 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í.

CampoDescripción
fromID del empleado que envía
toID del empleado que recibe
topicTema o canal del mensaje
type"message", "mention", "proposal", "command", "info", "task"
contentCuerpo del mensaje

Comportamientos clave:

  • Register anuncia a este empleado de IA en la red junto con sus capacidades
  • Subscribe/Unsubscribe gestionan las suscripciones a temas
  • Receive transmite 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:

TipoContenidoDescripción
"text"Fragmento de textoToken de texto en streaming
"tool_call"JSONEl modelo quiere llamar a una herramienta
"thinking"Fragmento de textoRazonamiento extendido
"error"Mensaje de errorAlgo salió mal
"done"VacíoEl 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.

RutaMecanismoPropósito
GET /api/v1/apps/{id}/ui/*Servidor de archivos estáticosSirve archivos de tu directorio ui/ (con respaldo de SPA a index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCRedirige 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
  • Triggers es 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:

ArchivoTamaño máximoDescripción
manifest.json1 MBMetadatos de la app
binary o app500 MBEjecutable
signatures.json1 MBFirmas Ed25519
TOOL.md1 MBInstrucciones 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

  1. Registra una cuenta de NeboAI en POST /api/v1/owners/register
  2. Inicia sesión para obtener un token JWT: POST /api/v1/owners/login
  3. 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

  1. Análisis automático: los binarios se analizan con VirusTotal
  2. Revisión administrativa: el equipo de NeboAI revisa los metadatos, el manifiesto y los resultados del análisis
  3. Si se aprueba: NeboAI firma la app con Ed25519 y la publica
  4. Si se rechaza: recibes el motivo y puedes corregirla y volver a enviarla

Tiempo de revisión objetivo: <24 horas.

Publicar actualizaciones

  1. Actualiza la versión de la app: PUT /api/v1/developer/apps/{id} con la nueva versión
  2. Sube binarios nuevos para cada plataforma
  3. 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

CampoDescripción
categoryp. ej., productividad, comunicación, herramientas para desarrolladores
iconURL del ícono de la app
visibilitypublic o private
descriptionPuede 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:

  1. Crea el directorio de tu app:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Escribe tu manifest.json y tu código
  3. Compila tu binario:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo detecta automáticamente el nuevo directorio (o reinicia Nebo)
  5. 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.log para 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_DATA para 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

SkillsApps
FormatoMarkdown (SKILL.md)Binario compilado (.napp)
EjecuciónSe inserta en el prompt del sistemaProceso aislado en sandbox mediante gRPC
OfreceGuía de comportamiento, metodologíaHerramientas, canales, paneles de interfaz
DuraciónLimitada a la sesión, vence por TTLSiempre en ejecución
CreaciónEscribir un archivo MarkdownEscribir, compilar, firmar, empaquetar
SeguridadNo requiere permisosSandbox 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).

CampoObligatorioValor predeterminadoDescripción
nameSí—Identificador único (se convierte en el slug)
descriptionSí—Descripción de una línea que se muestra en el catálogo de skills
versionNo"1.0.0"Semver para seguir las actualizaciones
authorNo—Autor de la skill
priorityNo0Mayor = se evalúa primero (100+ para anulaciones críticas)
max_turnsNo4Turnos de inactividad antes de que venza automáticamente
triggersNo[]Frases que activan automáticamente esta skill (coincidencia de subcadena sin distinguir mayúsculas)
toolsNo[]Herramientas que esta skill espera usar (informativo)
dependenciesNo[]Otras skills que deben estar instaladas
tagsNo[]Para clasificar y descubrir
platformNo[]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ónDescripciónEjemplo
catalogListar todas las skills disponiblesskill(action: "catalog")
loadActivar para esta sesiónskill(name: "code-review", action: "load")
unloadDesactivar una skillskill(name: "code-review", action: "unload")
createCrear una skill nueva en el discoskill(action: "create", content: "...")
updateActualizar una skill existenteskill(name: "my-skill", action: "update", content: "...")
deleteEliminar una skill del discoskill(name: "my-skill", action: "delete")

Cómo escribir buenas skills

Una buena plantilla de skill tiene:

  1. Un encabezado claro: le dice al empleado de IA en qué modo está
  2. Principios básicos: las reglas de comportamiento no negociables
  3. Metodología: un enfoque paso a paso para los escenarios comunes
  4. Ejemplos: patrones concretos de mensaje del usuario y respuesta
  5. 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:

SkillPrioridadDescripción
onboarding100Bienvenida a nuevos usuarios y recopilación de su perfil
best-friend50Skill de personalidad: relajada, leal, sin rodeos
debugging25Metodología de depuración sistemática
api-design15Buenas prácticas de diseño de API RESTful
code-review10Revisión de código estructurada con niveles de gravedad
database-expert10Diseño de bases de datos, consultas, optimización
git-workflow10Ramas de Git, commits, flujos de PR
security-audit10Aná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.

ArchivoServicioRPC principales
v0/common.proto(solo mensajes)HealthCheckRequest/Response, SettingsMap, UserContext, Empty
v0/tool.protoToolServiceName, Description, Schema, Execute, RequiresApproval, Configure
v0/channel.protoChannelServiceID, Connect, Disconnect, Send, Receive (stream), Configure
v0/comm.protoCommServiceName, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (stream), Configure
v0/gateway.protoGatewayServiceHealthCheck, Stream (stream), Poll, Cancel, Configure
v0/ui.protoUIServiceHealthCheck, HandleRequest, Configure
v0/schedule.protoScheduleServiceHealthCheck, 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 mensajeDescripción
ChannelSendRequestSobre de mensaje saliente con message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID de mensaje de la plataforma para los hilos
InboundMessageSobre de mensaje entrante con todos los campos comunes + timestamp
MessageSenderIdentidad del bot (name, role, botId), completada por el broker
AttachmentAdjunto de archivo, imagen o audio (type, url, filename, size)
MessageActionAcció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".