NeboAI
NeboAI
Inizia

Crea app per Nebo

Dai alla tua IA nuovi superpoteri. Strumenti, canali, gateway, pannelli UI: tutto ciò che riesci a immaginare, compilato in un binario nativo.

Panoramica

Che cos’è Nebo

Nebo è un assistente IA personale per desktop: un dipendente IA sempre attivo che gestisce la tua vita digitale. Pensa a Nebo come pensi a uno smartphone: una piattaforma potente che diventa rivoluzionaria grazie alle sue app.

Da solo, Nebo è già un dipendente IA capace, con memoria, pianificazione, navigazione web, gestione dei file e accesso alla shell. Ma la vera svolta sono le app. Come la forza di uno smartphone viene dal suo ecosistema di app, la forza di Nebo viene dalle app che estendono ciò che può fare.

Cosa sono le app

Le app di Nebo sono unità autonome e precompilate con funzionalità straordinarie. Ogni app dà a Nebo un nuovo superpotere: gestione del calendario, smistamento delle email, monitoraggio dei progetti, domotica, analisi finanziaria, tutto ciò che uno sviluppatore riesce a immaginare.

Le app offrono una potenza straordinaria in modo molto sicuro. Ogni app gira in una sandbox con permessi negati per impostazione predefinita. Può accedere solo a ciò che il suo manifest dichiara e che l’utente approva.

L’interfaccia è conversazionale al 100%. Gli utenti non interagiscono con le app tramite schermate o dashboard separate. Parlano con Nebo, e Nebo usa gli strumenti dell’app per portare a termine il lavoro. «Cosa ho in calendario domani?»: Nebo chiama l’app del calendario. «Crea una riunione con Sarah alle 15»: Nebo chiama l’app del calendario. L’utente non lascia mai la conversazione.

Le app possono offrire, se vogliono, una UI delle impostazioni: un pannello di configurazione che si apre nella finestra del browser integrato di Nebo. È qui che gli utenti inseriscono le chiavi API, attivano le funzioni e configurano l’app. La UI delle impostazioni è generata dall’array settings nel manifest (Nebo crea il modulo in automatico), oppure l’app può fornire una propria UI completamente personalizzata tramite la capability ui.

Le app sostituiscono ed estendono le funzioni integrate di Nebo. Nebo include strumenti di base della piattaforma (accesso al calendario locale, screenshot, ecc.). Quando installi un’app di calendario, questa sostituisce lo strumento di calendario integrato e ne diventa un’estensione completa: locale + cloud + aggregazione + verifica della disponibilità.

Criterio solo compilato

Nebo applica un criterio rigoroso: solo binari compilati. Tutte le app devono essere eseguibili nativi compilati.

StatoLinguaggi
SupportatiGo (consigliato), Rust, C/C++, Zig
RifiutatiPython, Node.js, Ruby, Java, .NET, script di shell

Motivazioni:

  • Prevenzione dell’automodifica da parte dell’IA: un dipendente IA con accesso alla shell potrebbe modificare il comportamento di uno script interpretato durante l’esecuzione. I binari compilati sono immutabili dopo la firma.
  • Integrità della firma: le firme Ed25519 coprono i byte grezzi del binario. Un binario firmato non può essere modificato senza invalidare la firma.
  • Applicazione della sandbox: la convalida del formato binario (magic byte ELF/Mach-O/PE) è un controllo rapido e affidabile.

Guida rapida

Installa l’SDK

Gli SDK ufficiali gestiscono tutta la configurazione del server gRPC, la gestione dei segnali e il collegamento del protocollo. Tu implementi solo le interfacce degli handler.

Go (consigliato):

go get github.com/neboloop/nebo-sdk-go

Rust (in arrivo):

# Coming soon
[dependencies]
nebo-sdk = "0.1"

C/C++ (in arrivo):

# Coming soon — Add as a CMake subdirectory or copy headers from sdk/c/include/

Struttura della cartella dell’app

Le app si trovano nella sottocartella apps/ della cartella dei dati di 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)

Checklist minima dell’app

  1. Crea manifest.json con id, name, version, provides
  2. Scrivi TOOL.md descrivendo come il dipendente IA deve usare il tuo strumento
  3. Installa l’SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Implementa l’interfaccia dell’handler per la tua capability (ToolHandler, ChannelHandler, ecc.)
  5. Registra l’handler e chiama app.Run()
  6. Compila un binario nativo (go build -o binary .)
  7. Metti il binario + manifest.json + TOOL.md nella cartella apps/<your-app-id>/
  8. Nebo lo rileva e lo avvia in automatico

Configurazione

manifest.json

Ogni app richiede 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
        }
    ]
}

Campi obbligatori:

CampoDescrizione
idIdentificatore in formato dominio inverso (ad es. com.mycompany.myapp)
nameNome leggibile
versionStringa semver
providesAlmeno una capability (vedi sotto)

Campi facoltativi:

CampoPredefinitoDescrizione
runtime"local""local" o "remote"
protocol"grpc"È supportato solo "grpc"
permissions[]Ciò a cui l’app deve accedere
description""Mostrato nella UI
settings[]Impostazioni configurabili (mostrate nella UI delle impostazioni)
oauth[]Requisiti del provider OAuth (vedi la sezione OAuth più sotto)

Capability

Dichiara cosa offre la tua app:

CapabilityServizio gRPCDescrizione
gatewayGatewayServiceInstradamento dei modelli LLM
tool:<name>ToolServiceUno strumento con nome per il dipendente IA
channel:<name>ChannelServiceUn canale di messaggistica
commCommServiceComunicazione tra dipendenti IA
uiUIServiceUI personalizzata con proxy HTTP
scheduleScheduleServicePianificazione personalizzata
visionToolServiceElaborazione visiva
browserToolServiceAutomazione del browser

Un’app può offrire più capability. Per esempio, un’app potrebbe offrire sia uno strumento sia un pannello UI.

Permessi

I permessi controllano ciò a cui l’app può accedere. Negati per impostazione predefinita: se non è dichiarato, l’app non può usarlo.

PrefissoEsempiDescrizione
network:network:outbound, network:*Accesso alla rete
filesystem:filesystem:read, filesystem:writeAccesso al file system
memory:memory:read, memory:writeAccesso alla memoria del dipendente IA
session:session:readSessioni di conversazione
tool:tool:shell, tool:fileUsare altri strumenti
shell:shell:execEsecuzione di comandi shell
channel:channel:send, channel:*Operazioni sui canali
comm:comm:send, comm:*Comunicazione tra dipendenti IA
model:model:chatAccesso ai modelli IA
user:user:tokenRicevere il JWT dell’utente nelle richieste
schedule:schedule:createGestione dei job cron
database:database:queryAccesso al database
storage:storage:read, storage:writeArchiviazione persistente
context:context:readAccesso al contesto del dipendente IA
subagent:subagent:spawnOperazioni sui sub-agent
lane:lane:enqueueOperazioni sulle lane
notification:notification:sendNotifiche push
embedding:embedding:searchAccesso agli embedding vettoriali
skill:skill:invokeInvocazione delle skill
advisor:advisor:consultAccesso al sistema di advisor
mcp:mcp:connectAccesso ai server MCP
voice:voice:recordAccesso a voce/audio
browser:browser:navigateAutomazione del browser
oauth:oauth:google, oauth:*Accesso ai token OAuth
settings:settings:readAccesso alle impostazioni
capability:capability:registerRegistrazione delle capability

Sono supportati i permessi con caratteri jolly: network:* corrisponde a qualsiasi controllo di permesso network:.

Impostazioni

Le impostazioni compaiono nella UI di Nebo, nel pannello delle impostazioni dell’app. Nebo le salva nel database e le invia alla tua app tramite la RPC Configure quando cambiano.

Lo schema delle tue impostazioni è incluso nella scheda dell’app store di NeboAI. Le app con impostazioni obbligatorie non configurate mostrano un badge «Da configurare» nella UI.

TipoDescrizione
textCampo di testo su una riga
passwordCampo di testo mascherato
toggleInterruttore booleano on/off
selectMenu a tendina con opzioni predefinite
numberCampo numerico
urlCampo URL con convalida
{
    "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"}
    ]
}

Requisiti OAuth

Le app possono dichiarare i requisiti del provider OAuth. Il broker OAuth di Nebo gestisce l’intero flusso: le app ricevono i token in automatico tramite la RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
CampoDescrizione
providerProvider OAuth: "google", "microsoft", "github"
scopesArray degli scope OAuth di cui l’app ha bisogno

Quando l’utente installa l’app, Nebo gli chiede di autorizzare gli scope OAuth richiesti. L’app riceve i token aggiornati tramite la RPC Configure senza dover gestire da sola il flusso OAuth.

Variabili d’ambiente

Il processo della tua app riceve un ambiente ripulito. Tutti i segreti vengono rimossi. Ricevi:

VariabileValore
NEBO_APP_DIRCartella di installazione dell’app
NEBO_APP_SOCKPercorso del socket Unix da creare
NEBO_APP_IDID dell’app dal manifest
NEBO_APP_NAMENome dell’app dal manifest
NEBO_APP_VERSIONVersione dell’app dal manifest
NEBO_APP_DATAPercorso della cartella data/ dell’app
PATHPATH di sistema (trasmesso così com’è)
HOMECartella home dell’utente (trasmessa così com’è)
TMPDIRCartella temporanea (trasmessa così com’è)

Importante: il tuo binario deve creare un server gRPC in ascolto sul socket Unix indicato da NEBO_APP_SOCK. Nebo attende fino a 10 secondi che il socket compaia.

Sequenza di avvio dell’app

  1. Nebo legge manifest.json e lo convalida
  2. Trova l’eseguibile binary o app nella cartella dell’app
  3. Controlla la presenza del marcatore .quarantined (si rifiuta di avviare le app in quarantena)
  4. Controllo di revoca (solo per le app distribuite da NeboAI)
  5. Verifica della firma (solo per le app distribuite da NeboAI, saltata in sviluppo)
  6. Convalida del binario (rifiuta link simbolici, script, file non eseguibili e file troppo grandi)
  7. Rimuove il socket rimasto dall’esecuzione precedente
  8. Crea la cartella data/ per l’archiviazione in sandbox
  9. Configura file di log per ogni app (logs/stdout.log, logs/stderr.log)
  10. Avvia il binario con un ambiente ripulito e l’isolamento del gruppo di processi
  11. Attende che compaia il socket Unix (backoff esponenziale, massimo 10 secondi)
  12. Si connette tramite gRPC sul socket Unix
  13. Crea client gRPC specifici per ogni capability in base a provides
  14. Esegue il controllo di integrità
  15. Registra le capability presso il dipendente IA (strumenti, gateway, comm, ecc.)

App strumento

Dichiara "provides": ["tool:my_tool_name"] nel tuo manifest.

Il pattern STRAP

Tutte le app strumento di Nebo devono usare lo STRAP (Single Tool Resource Action Pattern) per lo schema e l’instradamento dell’esecuzione. È lo stesso pattern che Nebo usa internamente per raggruppare oltre 35 strumenti singoli in 4 strumenti di dominio, riducendo di circa l’80% il carico di contesto dell’LLM.

Idea di fondo: invece di registrare più strumenti (get_events, check_availability, suggest_slots), registra UN solo strumento con i campi action (e, se serve, resource) che instradano verso l’handler giusto.

Esempio con una sola risorsa (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")

Esempio con più risorse (gestione progetti):

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")

Regole dello schema:

  1. Includi sempre un campo action come enum di stringhe obbligatorio
  2. Aggiungi un campo resource (enum di stringhe obbligatorio) solo se il tuo strumento gestisce più tipi di risorse distinti
  3. Tutti gli altri campi sono parametri specifici dell’azione
  4. La descrizione dell’enum action deve elencare tutte le azioni disponibili

Perché lo STRAP è importante:

  • Gli LLM imparano una volta il pattern di instradamento action e lo applicano a tutte le operazioni
  • Le definizioni degli strumenti occupano circa il 6% del contesto: lo STRAP lo riduce dell’80%
  • Le nuove operazioni sono solo voci aggiunte all’enum, non nuove registrazioni di strumenti
  • Funziona allo stesso modo con modelli ospitati e locali

Esempio in Go: strumento calcolatrice

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 installa:

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/

Esempio in 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(())
}

Esempio in 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;
}

App canale

Dichiara "provides": ["channel:my_channel"] e "permissions": ["channel:send"].

Le app canale collegano piattaforme di messaggistica esterne (Telegram, Discord, Slack, ecc.) al dipendente IA di Nebo. Quando un utente invia un messaggio sulla piattaforma esterna, la tua app lo trasmette a Nebo tramite Receive. Quando il dipendente IA vuole rispondere, Nebo chiama Send della tua app.

Come funziona

  1. Nebo chiama ID() per ottenere l’identificatore univoco del tuo canale
  2. Nebo chiama Connect() con la configurazione presa dalle impostazioni della tua app
  3. Nebo apre uno stream Receive(): la tua app invia i messaggi in arrivo ogni volta che un utente scrive al bot
  4. I messaggi in arrivo vengono instradati verso la lane di conversazione principale del dipendente IA
  5. Quando il dipendente IA vuole inviare un messaggio, Nebo chiama Send() con la busta del messaggio v1
  6. Allo spegnimento, Nebo chiama Disconnect()

Busta del messaggio v1

Tutti i messaggi dei canali, in arrivo e in uscita, usano la busta del messaggio comune:

{
  "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"
}
CampoTipoDescrizione
message_idUUID v7ID univoco ordinato nel tempo
channel_id{type}:{platform_id}Identificatore del canale instradabile
senderobjectIdentità del bot: nome, ruolo, botId
textstringCorpo del messaggio
attachmentsarrayFile, immagini, audio
reply_toUUID v7ID del messaggio padre per i thread
actionsarrayPulsanti/tastiere interattivi
platform_databytesDati trasmessi così come sono per le funzioni specifiche della piattaforma
timestampISO 8601Lo imposta chi pubblica

Struttura a due livelli: i campi comuni (text, attachments, reply_to, actions) coprono il 90% dei messaggi avviati dai dipendenti. Le funzioni specifiche della piattaforma vanno in platform_data: il tuo plugin le converte da e verso il formato nativo della piattaforma.

Stream di conversazione

I messaggi dei canali vengono instradati su stream di conversazione separati per ogni canale, per garantire l’isolamento:

neboai/bot/{botID}/channels/{channelType}/inbound    # messages from users → agent
neboai/bot/{botID}/channels/{channelType}/outbound   # messages from agent → channel

Esempio in Go: canale 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
        }
    ]
}

Altre capability

App comm

Dichiara "provides": ["comm"] e "permissions": ["comm:*"]. Le app comm permettono la comunicazione tra dipendenti IA.

CampoDescrizione
fromID del dipendente mittente
toID del dipendente destinatario
topicArgomento/canale del messaggio
type"message", "mention", "proposal", "command", "info", "task"
contentCorpo del messaggio

Comportamenti principali:

  • Register annuncia questo dipendente IA sulla rete con le sue capability
  • Subscribe/Unsubscribe gestiscono le iscrizioni agli argomenti
  • Receive trasmette i messaggi in arrivo (streaming lato server, come per i canali)
  • Può essere attiva una sola app comm alla volta

App gateway

Un’app gateway instrada le richieste LLM verso i modelli. Dichiara "provides": ["gateway"] e "permissions": ["network:outbound", "user:token"].

GatewayRequest contiene messaggi, strumenti, prompt di sistema, numero massimo di token, temperatura e un UserContext (il token JWT, se è concesso il permesso user:token).

Tipi di GatewayEvent:

TipoContenutoDescrizione
"text"Porzione di testoToken di testo in streaming
"tool_call"JSONIl modello vuole chiamare uno strumento
"thinking"Porzione di testoRagionamento esteso
"error"Messaggio di erroreQualcosa è andato storto
"done"VuotoLo stream è terminato

App UI

Un’app UI offre un’interfaccia di configurazione personalizzata che si apre nella finestra del browser integrato di Nebo. Dichiara "provides": ["ui"]. A differenza del modulo di impostazioni automatico (che Nebo genera dal manifest settings), un’app UI serve un proprio frontend completo in HTML/CSS/JS.

La tua app include una cartella ui/ con risorse web statiche (HTML, CSS, JS, di solito una SPA con index.html). Nebo serve questi file direttamente e inoltra le chiamate API alla tua app tramite gRPC.

PercorsoMeccanismoScopo
GET /api/v1/apps/{id}/ui/*Server di file staticiServe i file dalla tua cartella ui/ (fallback SPA su index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCInoltra le richieste HTTP a UIService.HandleRequest() della tua app

L’SDK incapsula un normale net/http.ServeMux, così scrivi i soliti handler HTTP in Go: il collegamento gRPC lo gestisce l’SDK in automatico.

Esempio in Go: UI dashboard:

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())
}

Il tuo ui/index.html farebbe chiamate fetch a /api/v1/apps/com.example.dashboard/api/status, che vengono inoltrate al tuo handler mux.

App di pianificazione

Un’app di pianificazione sostituisce lo scheduler cron integrato di Nebo. Dichiara "provides": ["schedule"] e "permissions": ["schedule:create"].

Quando la tua app di pianificazione si avvia, Nebo instrada tutta la pianificazione attraverso la tua app invece del motore cron predefinito. Se la tua app si arresta in modo anomalo, Nebo torna in automatico al motore integrato.

  • La tua app possiede lo stato delle pianificazioni: quando è attiva un’app di pianificazione, Nebo non salva le pianificazioni nel proprio DB
  • CRUD standard: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers è una RPC in streaming lato server: la tua app invia un messaggio di attivazione ogni volta che scatta una pianificazione
  • Può essere attiva una sola app di pianificazione alla volta

App con più capability

Un’app può offrire più capability. Per esempio, un’app dashboard con sia uno strumento sia una UI:

{
    "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())

Pacchettizzazione

Formato .napp

Per la distribuzione tramite NeboAI, crea il pacchetto della tua app come file .napp (un archivio tar.gz):

cd com.example.myapp/
tar -czf myapp-1.0.0.napp manifest.json binary signatures.json TOOL.md

File obbligatori:

FileDimensione massimaDescrizione
manifest.json1 MBMetadati dell’app
binary o app500 MBEseguibile
signatures.json1 MBFirme Ed25519
TOOL.md1 MBIstruzioni dello strumento per il dipendente IA

Regole di sicurezza durante l’estrazione:

  • Nessun attraversamento di percorso (../ rifiutato)
  • Nessun link simbolico (rifiutati)
  • Nessun percorso assoluto (rifiutati)
  • Sono accettati solo nomi di file consentiti

Firme

NeboAI firma le app con Ed25519. Il formato di 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>"
}

In modalità sviluppo (nessun URL di NeboAI configurato), la verifica della firma viene saltata del tutto. Non ti serve signatures.json per lo sviluppo locale.

Pubblicazione

Quando la tua app funziona in locale, pubblicala tramite NeboAI per distribuirla a tutti gli utenti di Nebo.

Configurazione dell’account sviluppatore

  1. Registra un account NeboAI con POST /api/v1/owners/register
  2. Accedi per ottenere un token JWT: POST /api/v1/owners/login
  3. Crea un account sviluppatore: POST /api/v1/developer/accounts

Flusso di invio

draft → pending_review → [approved] → published
                       → [rejected] → draft (fix and resubmit)

Passo 1: crea l’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"
  }'

Passo 2: carica i binari per piattaforma

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"

Carica un binario per ogni piattaforma: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Passo 3: invia per la revisione

curl -X POST https://neboai.com/api/v1/developer/apps/{id}/submit \
  -H "Authorization: Bearer $TOKEN"

Processo di revisione

  1. Scansione automatica: i binari vengono analizzati con VirusTotal
  2. Revisione amministrativa: il team di NeboAI esamina metadati, manifest e risultati della scansione
  3. In caso di approvazione: NeboAI firma l’app con Ed25519 e la pubblica
  4. In caso di rifiuto: ricevi una motivazione e puoi correggere e inviare di nuovo

Tempo di revisione previsto: <24 ore.

Pubblicare aggiornamenti

  1. Aggiorna la versione dell’app: PUT /api/v1/developer/apps/{id} con la nuova versione
  2. Carica i nuovi binari per ogni piattaforma
  3. Invia di nuovo per la revisione

Ogni aggiornamento passa per lo stesso processo di revisione. Le versioni precedenti restano disponibili finché la nuova versione non viene approvata.

Metadati dello store

CampoDescrizione
categoryad es. productivity, communication, developer-tools
iconURL dell’icona dell’app
visibilitypublic o private
descriptionPuò essere più lunga e ricca della descrizione nel manifest

Flusso di sviluppo

Sviluppo locale

Per lo sviluppo locale non serve alcun pacchetto:

  1. Crea la directory della tua app:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Scrivi il tuo manifest.json e il codice
  3. Compila il tuo binario:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo rileva in automatico la nuova cartella (oppure riavvia Nebo)
  5. Dopo aver modificato il codice, ricompila il binario: il monitoraggio dei file riavvierà l’app

Visualizzare i log

Lo stdout/stderr dell’app viene salvato in file di log separati per ogni 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

Dati persistenti

Usa la cartella data/ (disponibile anche come variabile d’ambiente NEBO_APP_DATA) per tutti i file che la tua app deve conservare. Questa cartella sopravvive agli aggiornamenti dell’app e alla quarantena.

Suggerimenti per il debug

  • Se la tua app non si avvia, controlla logs/stderr.log per eventuali errori
  • Assicurati che il binario sia eseguibile (chmod +x binary)
  • Assicurati di essere in ascolto sul percorso del socket Unix indicato da NEBO_APP_SOCK
  • Il socket deve essere pronto entro 10 secondi dall’avvio
  • Usa NEBO_APP_DATA per l’archiviazione, non percorsi scritti nel codice
  • Scrivi su stderr per i log di debug (salvati in logs/stderr.log)

Verifica

# 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

Disinstallazione

nebo apps uninstall com.example.myapp

Skill

Cosa sono le skill

Le skill sono insiemi di istruzioni che determinano come si comporta Nebo durante una conversazione. Quando una skill è attiva, il suo contenuto viene inserito direttamente nel prompt di sistema e guida il tono, il metodo, le competenze di settore e l’uso degli strumenti del dipendente IA per quella sessione.

Le skill non sono codice. Sono documenti markdown con metadati YAML. Niente compilazione, niente binario, niente gRPC. Una skill è un file SKILL.md in una cartella. Tutto qui.

Le skill sono contestuali e temporanee. Si attivano quando servono (tramite corrispondenza con i trigger o caricamento manuale), restano attive per qualche turno e scadono quando non servono più. Così il contesto del dipendente IA resta leggero: nel prompt c’è solo la guida che conta in quel momento.

Le skill completano le app. Le app offrono capacità eseguibili (strumenti, canali, gateway). Le skill offrono indicazioni di coordinamento: come usare bene quegli strumenti. Un’app di calendario dà a Nebo la capacità di leggere e scrivere eventi. Una skill di «preparazione riunioni» dice a Nebo come prepararsi alle riunioni usando insieme quell’app di calendario, l’email e la ricerca web.

Skill e app a confronto

SkillApp
FormatoMarkdown (SKILL.md)Binario compilato (.napp)
EsecuzioneInserite nel prompt di sistemaProcesso in sandbox tramite gRPC
OffronoIndicazioni di comportamento, metodoStrumenti, canali, pannelli UI
DurataLimitata alla sessione, scadenza basata su TTLSempre in esecuzione
CreazioneScrivi un file markdownScrivi, compila, firma, crea il pacchetto
SicurezzaNessun permesso necessarioSandbox con permessi negati per impostazione predefinita

Guida rapida

Crea una cartella nella cartella delle skill di Nebo con un file SKILL.md:

~/Library/Application Support/Nebo/skills/   # macOS
~/.config/nebo/skills/                        # Linux
%AppData%\Nebo\skills\                        # Windows
mkdir -p ~/.config/nebo/skills/my-skill

Scrivi 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 monitora la cartella delle skill con fsnotify. La tua skill è subito disponibile, senza bisogno di riavviare. Scrivi qualcosa che corrisponde a un trigger e si attiva da sola.

Oppure chiedilo direttamente a Nebo: «Crea una skill per scrivere articoli del blog», e Nebo scriverà il file SKILL.md per te.

Formato di SKILL.md

Ogni skill è un singolo file SKILL.md composto da due parti: un frontmatter YAML tra i marcatori --- e un corpo in markdown (le istruzioni vere e proprie inserite nel prompt di sistema).

CampoObbligatorioPredefinitoDescrizione
nameSì—Identificatore univoco (diventa lo slug)
descriptionSì—Descrizione di una riga mostrata nel catalogo delle skill
versionNo"1.0.0"Semver per tenere traccia degli aggiornamenti
authorNo—Autore della skill
priorityNo0Più alto = valutato per primo (100+ per le sostituzioni critiche)
max_turnsNo4Turni di inattività prima della scadenza automatica
triggersNo[]Frasi che attivano in automatico questa skill (corrispondenza di sottostringa, senza distinzione tra maiuscole e minuscole)
toolsNo[]Strumenti che questa skill prevede di usare (a titolo informativo)
dependenciesNo[]Altre skill che devono essere installate
tagsNo[]Per la classificazione e la ricerca
platformNo[]Piattaforme supportate: macos, linux, windows (vuoto = tutte)

Come si attivano le skill

Le skill seguono un modello di attivazione in due fasi: prima il suggerimento, poi l’invocazione.

Fase 1: corrispondenza dei trigger. Ogni volta che un utente invia un messaggio, Nebo esamina tutte le skill registrate per trovare corrispondenze con i trigger. Le skill corrispondenti compaiono come suggerimenti nel prompt di sistema. Il dipendente IA vede il suggerimento e decide se invocare la skill.

Fase 2: invocazione. Il dipendente IA invoca una skill chiamando:

skill(name: "code-review")

Questo restituisce l’intero modello SKILL.md come risultato dello strumento, registra l’invocazione e reinserisce il modello nel prompt di sistema nei turni successivi.

TTL e scadenza:

  • Skill attivate per corrispondenza: 4 turni di inattività (configurabile con max_turns)
  • Skill caricate manualmente: 6 turni di inattività
  • Una nuova invocazione azzera il timer
  • Limite massimo: 4 skill attive per sessione
  • Budget di token: il contenuto complessivo delle skill attive è limitato a 16.000 caratteri

Gestire le skill

Il dipendente IA può gestire le skill tramite lo strumento skill:

AzioneDescrizioneEsempio
catalogElenca tutte le skill disponibiliskill(action: "catalog")
loadAttiva per questa sessioneskill(name: "code-review", action: "load")
unloadDisattiva una skillskill(name: "code-review", action: "unload")
createCrea una nuova skill su discoskill(action: "create", content: "...")
updateAggiorna una skill esistenteskill(name: "my-skill", action: "update", content: "...")
deleteElimina una skill dal discoskill(name: "my-skill", action: "delete")

Scrivere buone skill

Un buon modello di skill contiene:

  1. Un titolo chiaro: dice al dipendente IA in quale modalità si trova
  2. Principi fondamentali: le regole di comportamento non negoziabili
  3. Metodo: l’approccio passo passo per i casi più comuni
  4. Esempi: schemi concreti di messaggio dell’utente e risposta
  5. Cose da evitare: cosa NON fare (i modelli imparano bene dagli esempi negativi)

Suggerimento: ogni skill dovrebbe fare bene una sola cosa. Non creare una skill di «programmazione generale»: crea code-review, debugging, api-design come skill separate. Il dipendente IA può averne più di una attiva nello stesso momento.

Skill incluse

Nebo include skill che coprono i casi d’uso più comuni:

SkillPrioritàDescrizione
onboarding100Benvenuto ai nuovi utenti e raccolta del profilo
best-friend50Skill di personalità: informale, leale, parla chiaro
debugging25Metodo di debug sistematico
api-design15Buone pratiche di progettazione di API RESTful
code-review10Revisione del codice strutturata con livelli di gravità
database-expert10Progettazione di database, query, ottimizzazione
git-workflow10Branch Git, commit, flussi di lavoro delle PR
security-audit10Analisi della sicurezza e rilevamento delle vulnerabilità

Servono sia come utili impostazioni predefinite sia come implementazioni di riferimento per creare le tue skill.

Riferimento

File proto

I file proto si trovano in proto/apps/v0/. Gli SDK includono codice già generato, quindi per lo sviluppo normale non ti serve protoc.

FileServizioRPC principali
v0/common.proto(solo messaggi)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

Ogni servizio include le RPC HealthCheck e Configure. L’SDK le gestisce entrambe in automatico.

Tipi proto dei canali

Tipo di messaggioDescrizione
ChannelSendRequestBusta del messaggio in uscita con message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID del messaggio della piattaforma per i thread
InboundMessageBusta del messaggio in arrivo con tutti i campi comuni + timestamp
MessageSenderIdentità del bot (name, role, botId), arricchita dal broker
AttachmentAllegato file/immagine/audio (type, url, filename, size)
MessageActionAzione interattiva con pulsante/tastiera (label, callback_id)

Identità e ruoli dei bot

I bot di Nebo hanno un modello di identità su tre assi:

  • creature: che cos’è il bot (archetipo): «Stratega dalla battuta pronta», «Ricercatore meticoloso»
  • role: che rapporto ha con l’utente (relazione): «Amico», «COO», «Mentore»
  • vibe: la sua energia (stile di comunicazione): «Rilassato ma con le idee chiare», «Caloroso e incoraggiante»

Quando il tuo plugin di canale riceve un messaggio in uscita, il campo sender contiene il name e il role del bot. Usali per formattare il nome visualizzato sulla tua piattaforma. Il ruolo non è una qualifica professionale: descrive una relazione. «Amico», «Figlio» e «Mentore» sono ruoli validi tanto quanto «COO» e «DevLead».