Descripción general
Qué es Nebo
Nebo es un asistente de IA personal para el escritorio: un empleado de IA siempre activo que gestiona 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 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 de verdad lo desbloquea todo son las apps. Igual que la potencia de un smartphone viene de su ecosistema de apps, la potencia de Nebo viene de las apps que amplían lo que puede hacer.
Qué son las apps
Las apps de Nebo son unidades autónomas y precompiladas con una funcionalidad increíble. Cada app le da a Nebo un nuevo superpoder: gestión del calendario, clasificación del correo, seguimiento de proyectos, domótica, análisis financiero... todo lo que un desarrollador pueda imaginar.
Las apps ofrecen una potencia increíble de forma muy segura. Cada app se ejecuta en un entorno aislado 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 a través de pantallas o paneles separados. Hablan con Nebo, y Nebo usa las herramientas de la app para hacer las cosas. «¿Qué tengo mañana en el calendario?»: Nebo llama a la app de calendario. «Crea una reunión con Sarah a las 3 de la tarde»: Nebo llama a la app de calendario. El usuario nunca sale de la conversación.
Las apps pueden ofrecer opcionalmente una interfaz de configuración: un panel de configuración que se abre en la ventana del navegador integrado de Nebo. Ahí es donde los usuarios introducen claves de API, activan funciones y configuran la app. La interfaz de configuración se genera a partir del array settings del manifiesto (Nebo dibuja el formulario automáticamente), o bien la app puede ofrecer su propia interfaz personalizada completa mediante la capacidad ui.
Las apps sustituyen 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, sustituye a la herramienta de calendario integrada y se convierte en un superconjunto: local + nube + agregación + comprobación de disponibilidad.
Política de solo compilados
Nebo aplica una política estricta de binarios exclusivamente compilados. Todas las apps deben ser ejecutables nativos compilados.
| Estado | Lenguajes |
|---|---|
| Admitidos | Go (recomendado), Rust, C/C++, Zig |
| Rechazados | Python, Node.js, Ruby, Java, .NET, scripts de shell |
Motivos:
- Evitar que la IA se modifique a sí misma: 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 una vez firmados.
- Integridad de la firma: las firmas Ed25519 cubren los bytes en bruto del binario. Un binario firmado no se puede modificar sin invalidar la firma.
- Aplicación del aislamiento: la validación del formato binario (bytes mágicos ELF/Mach-O/PE) es un filtro rápido y fiable.
Inicio rápido
Instala el SDK
Los SDK oficiales se encargan de toda la configuración del servidor gRPC, la gestión de señales y el puente del protocolo. 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 de directorios de una app
Las apps se encuentran 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 de comprobación de una app mínima
- 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 necesita 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 de dominio inverso (p. ej., com.mycompany.myapp) |
name | Nombre legible |
version | Cadena semver |
provides | Al menos una capacidad (ver más 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 | [] | Ajustes configurables (se muestran en la interfaz de Configuración) |
oauth | [] | Requisitos del proveedor OAuth (consulta 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 a la vez una herramienta y 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/audio |
browser: | browser:navigate | Automatización del navegador |
oauth: | oauth:google, oauth:* | Acceso a tokens OAuth |
settings: | settings:read | Acceso a la configuración |
capability: | capability:register | Registro de capacidades |
Se admiten permisos comodín: network:* coincide con cualquier comprobación de permiso network:.
Configuración
Los ajustes aparecen en la interfaz de Nebo, en el panel de configuración de la app. Nebo los guarda en la base de datos y los envía a tu app mediante la RPC Configure cuando cambian.
Tu esquema de ajustes se incluye en la ficha de la tienda de apps de NeboAI. Las apps con ajustes obligatorios sin configurar muestran una insignia «Requiere configuración» en la interfaz.
| Tipo | Descripción |
|---|---|
text | Campo de texto de una sola línea |
password | Campo de texto oculto |
toggle | Interruptor booleano de activado/desactivado |
select | 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 OAuth. El intermediario OAuth de Nebo gestiona todo el flujo: las apps reciben los tokens automáticamente mediante la RPC Configure.
{
"oauth": [
{
"provider": "google",
"scopes": ["https://www.googleapis.com/auth/calendar"]
}
]
} | Campo | Descripción |
|---|---|
provider | Proveedor OAuth: "google", "microsoft", "github" |
scopes | Array de ámbitos OAuth que necesita la app |
Cuando el usuario instala la app, Nebo le pide que autorice los ámbitos OAuth necesarios. La app recibe los tokens renovados mediante la RPC Configure sin tener que gestionar ella misma el flujo OAuth.
Variables de entorno
El proceso de tu app recibe un entorno saneado. 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 hay que 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 transmite tal cual) |
HOME | Directorio personal del usuario (se transmite tal cual) |
TMPDIR | Directorio temporal (se transmite 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 una app
- Nebo lee
manifest.jsony lo valida - Busca el ejecutable
binaryoappen el directorio de la app - Comprueba si existe el marcador
.quarantined(se niega a iniciar apps en cuarentena) - Comprobación de revocación (solo apps distribuidas por NeboAI)
- Verificación de la 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 saneado y aislamiento del grupo de procesos
- Espera a que aparezca el socket Unix (espera exponencial, máximo 10 segundos)
- Se conecta mediante gRPC a través del socket Unix
- Crea clientes gRPC específicos para cada capacidad según
provides - Ejecuta una comprobación de estado
- Registra las capacidades en el empleado de IA (herramientas, pasarela, comunicación, 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 un ~80 %.
Idea principal: en lugar de registrar varias herramientas (get_events, check_availability, suggest_slots), registra UNA sola herramienta con campos action (y, opcionalmente, 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 - Añade 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 nuevos registros de herramientas
- 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": []
} Compilar e instalar:
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 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 los ajustes de tu app - Nebo abre un stream
Receive(): tu app envía los mensajes entrantes cada vez que un usuario 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, tanto entrantes como 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 principal para los hilos |
actions | array | Botones/teclados interactivos |
platform_data | bytes | Datos opacos que se transmiten tal cual para funciones específicas de la plataforma |
timestamp | ISO 8601 | Lo establece el emisor |
Diseño de dos capas: los campos comunes (text, attachments, reply_to, actions) cubren el 90 % de los mensajes iniciados por los empleados. Las funciones específicas de cada plataforma van en platform_data: tu plugin las traduce al formato nativo de la plataforma y viceversa.
Streams de conversación
Los mensajes de canal se enrutan por streams de conversación propios de 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 remitente |
to | ID del empleado destinatario |
topic | Tema/canal del mensaje |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Cuerpo del mensaje |
Comportamientos clave:
Registeranuncia este empleado de IA en la red junto con sus capacidadesSubscribe/Unsubscribegestionan las suscripciones a temasReceivetransmite los mensajes entrantes (streaming desde el servidor, igual que los canales)- Solo puede haber una app de comunicación activa a la vez
App de pasarela
Una app de pasarela enruta las solicitudes LLM a 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 ha fallado |
"done" | Vacío | El stream ha terminado |
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 genera a partir del settings de tu manifiesto), 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 | Finalidad |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Servidor de archivos estáticos | Sirve archivos de tu directorio ui/ (con respaldo 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 del puente gRPC automáticamente.
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 sustituye al programador cron integrado de Nebo. Declara "provides": ["schedule"] y "permissions": ["schedule:create"].
Cuando tu app de programación se inicia, 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 la dueña del estado de la programación: Nebo no guarda las 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 una RPC con streaming desde el 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 distribuir tu app a través de NeboAI, empaquétala 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 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 en local, 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 del administrador: 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 nuevos binarios 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., productivity, communication, developer-tools |
icon | URL del icono de la app |
visibility | public o private |
description | Puede ser más larga y completa que la descripción del manifiesto |
Flujo de desarrollo
Desarrollo local
No hace falta empaquetar nada 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)
- Tras cambiar el código, vuelve a compilar el binario: el vigilante 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 variable de entorno NEBO_APP_DATA) para cualquier archivo que tu app necesite conservar. Este directorio sobrevive a las actualizaciones de la app y a la cuarentena.
Consejos de depuración
- Si tu app no se inicia, revisa
logs/stderr.logen busca de 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 en 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 determinan cómo se comporta Nebo durante una conversación. Cuando una skill está activa, su contenido se inyecta directamente en el prompt del sistema y orienta el tono, la metodología, el conocimiento del área y el uso de herramientas del empleado de IA durante 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. Nada más.
Las skills son contextuales y temporales. Se activan cuando son relevantes (por coincidencia de activadores o carga manual), se mantienen durante unos cuantos turnos y caducan cuando dejan de hacer falta. Así el contexto del empleado de IA se mantiene ligero: en el prompt solo está la orientación que importa en ese momento.
Las skills complementan a las apps. Las apps aportan capacidades ejecutables (herramientas, canales, pasarelas). Las skills aportan orientación para coordinarlo todo: cómo usar bien esas herramientas. Una app de calendario le da a Nebo la capacidad de leer y escribir eventos. Una skill de «preparación de reuniones» le dice a Nebo cómo preparar reuniones usando a la vez esa app de calendario, el correo y la búsqueda web.
Skills frente a apps
| Skills | Apps | |
|---|---|---|
| Formato | Markdown (SKILL.md) | Binario compilado (.napp) |
| Ejecución | Se inyecta en el prompt del sistema | Proceso aislado mediante gRPC |
| Aporta | Orientación de comportamiento, metodología | Herramientas, canales, paneles de interfaz |
| Duración | Limitada a la sesión, caducidad por TTL | Siempre en ejecución |
| Creación | Escribir un archivo markdown | Escribir, compilar, firmar, empaquetar |
| Seguridad | No requiere permisos | Entorno aislado 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 activador 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 inyectan 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 hacer seguimiento de las actualizaciones |
author | No | — | Autor de la skill |
priority | No | 0 | Cuanto más alto, antes coincide (100+ para anulaciones críticas) |
max_turns | No | 4 | Turnos de inactividad antes de caducar automáticamente |
triggers | No | [] | Frases que activan automáticamente esta skill (coincidencia de subcadena sin distinguir mayúsculas y minúsculas) |
tools | No | [] | Herramientas que esta skill espera usar (informativo) |
dependencies | No | [] | Otras skills que deben estar instaladas |
tags | No | [] | Para la clasificación y el descubrimiento |
platform | No | [] | Plataformas admitidas: macos, linux, windows (vacío = todas) |
Cómo se activan las skills
Las skills siguen un modelo de activación en dos fases: primero la sugerencia, después la invocación.
Fase 1: Coincidencia de activadores. Cada vez que un usuario envía un mensaje, Nebo revisa todas las skills registradas en busca de activadores 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 SKILL.md completa como resultado de la herramienta, registra la invocación y vuelve a inyectar la plantilla en el prompt del sistema en los turnos siguientes.
TTL y caducidad:
- Skills activadas automáticamente: 4 turnos de inactividad (configurable con
max_turns) - Skills cargadas manualmente: 6 turnos de inactividad
- Volver a invocarla reinicia el temporizador
- Límite estricto: un máximo de 4 skills activas por sesión
- Presupuesto de tokens: el contenido combinado de las skills activas tiene un límite de 16.000 caracteres
Gestión de skills
El empleado de IA puede gestionar las skills mediante la herramienta skill:
| Acción | Descripción | Ejemplo |
|---|---|---|
catalog | Lista todas las skills disponibles | skill(action: "catalog") |
load | Activa para esta sesión | skill(name: "code-review", action: "load") |
unload | Desactiva una skill | skill(name: "code-review", action: "unload") |
create | Crea una skill nueva en el disco | skill(action: "create", content: "...") |
update | Actualiza una skill existente | skill(name: "my-skill", action: "update", content: "...") |
delete | Elimina 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 innegociables
- Metodología: el enfoque paso a paso para los casos habituales
- Ejemplos: patrones concretos de mensaje del usuario y respuesta
- Antipatrones: lo que NO hay que 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 a la vez.
Skills incluidas
Nebo incluye skills que cubren los casos de uso más habituales:
| Skill | Prioridad | Descripción |
|---|---|---|
onboarding | 100 | Bienvenida a nuevos usuarios y recogida del perfil |
best-friend | 50 | Skill de personalidad: cercana, leal, hablando claro |
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 tanto como valores predeterminados útiles 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 |
Todos los servicios incluyen las RPC HealthCheck y Configure. El SDK gestiona ambas 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 del mensaje en la plataforma para los hilos |
InboundMessage | Sobre de mensaje entrante con todos los campos comunes + marca de tiempo |
MessageSender | Identidad del bot (name, role, botId), enriquecida por el intermediario |
Attachment | Archivo adjunto de archivo/imagen/audio (type, url, filename, size) |
MessageAction | Acción interactiva de botón/teclado (label, callback_id) |
Identidad y roles de los bots
Los bots de Nebo tienen un modelo de identidad de tres ejes:
- creature: qué es el bot (arquetipo): «Estratega ingenioso», «Investigador meticuloso»
- role: qué relación tiene con el usuario: «Amigo», «Director de operaciones», «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 visible en tu plataforma. El rol no es un cargo: describe una relación. «Amigo», «Hijo» y «Mentor» son roles válidos, igual que «Director de operaciones» y «Jefe de desarrollo».