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.
| Stato | Linguaggi |
|---|---|
| Supportati | Go (consigliato), Rust, C/C++, Zig |
| Rifiutati | Python, 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
- Crea
manifest.jsonconid,name,version,provides - Scrivi
TOOL.mddescrivendo come il dipendente IA deve usare il tuo strumento - Installa l’SDK (
go get github.com/neboloop/nebo-sdk-go) - Implementa l’interfaccia dell’handler per la tua capability (
ToolHandler,ChannelHandler, ecc.) - Registra l’handler e chiama
app.Run() - Compila un binario nativo (
go build -o binary .) - Metti il binario + manifest.json + TOOL.md nella cartella
apps/<your-app-id>/ - 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:
| Campo | Descrizione |
|---|---|
id | Identificatore in formato dominio inverso (ad es. com.mycompany.myapp) |
name | Nome leggibile |
version | Stringa semver |
provides | Almeno una capability (vedi sotto) |
Campi facoltativi:
| Campo | Predefinito | Descrizione |
|---|---|---|
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:
| Capability | Servizio gRPC | Descrizione |
|---|---|---|
gateway | GatewayService | Instradamento dei modelli LLM |
tool:<name> | ToolService | Uno strumento con nome per il dipendente IA |
channel:<name> | ChannelService | Un canale di messaggistica |
comm | CommService | Comunicazione tra dipendenti IA |
ui | UIService | UI personalizzata con proxy HTTP |
schedule | ScheduleService | Pianificazione personalizzata |
vision | ToolService | Elaborazione visiva |
browser | ToolService | Automazione 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.
| Prefisso | Esempi | Descrizione |
|---|---|---|
network: | network:outbound, network:* | Accesso alla rete |
filesystem: | filesystem:read, filesystem:write | Accesso al file system |
memory: | memory:read, memory:write | Accesso alla memoria del dipendente IA |
session: | session:read | Sessioni di conversazione |
tool: | tool:shell, tool:file | Usare altri strumenti |
shell: | shell:exec | Esecuzione di comandi shell |
channel: | channel:send, channel:* | Operazioni sui canali |
comm: | comm:send, comm:* | Comunicazione tra dipendenti IA |
model: | model:chat | Accesso ai modelli IA |
user: | user:token | Ricevere il JWT dell’utente nelle richieste |
schedule: | schedule:create | Gestione dei job cron |
database: | database:query | Accesso al database |
storage: | storage:read, storage:write | Archiviazione persistente |
context: | context:read | Accesso al contesto del dipendente IA |
subagent: | subagent:spawn | Operazioni sui sub-agent |
lane: | lane:enqueue | Operazioni sulle lane |
notification: | notification:send | Notifiche push |
embedding: | embedding:search | Accesso agli embedding vettoriali |
skill: | skill:invoke | Invocazione delle skill |
advisor: | advisor:consult | Accesso al sistema di advisor |
mcp: | mcp:connect | Accesso ai server MCP |
voice: | voice:record | Accesso a voce/audio |
browser: | browser:navigate | Automazione del browser |
oauth: | oauth:google, oauth:* | Accesso ai token OAuth |
settings: | settings:read | Accesso alle impostazioni |
capability: | capability:register | Registrazione 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.
| Tipo | Descrizione |
|---|---|
text | Campo di testo su una riga |
password | Campo di testo mascherato |
toggle | Interruttore booleano on/off |
select | Menu a tendina con opzioni predefinite |
number | Campo numerico |
url | Campo 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"]
}
]
} | Campo | Descrizione |
|---|---|
provider | Provider OAuth: "google", "microsoft", "github" |
scopes | Array 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:
| Variabile | Valore |
|---|---|
NEBO_APP_DIR | Cartella di installazione dell’app |
NEBO_APP_SOCK | Percorso del socket Unix da creare |
NEBO_APP_ID | ID dell’app dal manifest |
NEBO_APP_NAME | Nome dell’app dal manifest |
NEBO_APP_VERSION | Versione dell’app dal manifest |
NEBO_APP_DATA | Percorso della cartella data/ dell’app |
PATH | PATH di sistema (trasmesso così com’è) |
HOME | Cartella home dell’utente (trasmessa così com’è) |
TMPDIR | Cartella 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
- Nebo legge
manifest.jsone lo convalida - Trova l’eseguibile
binaryoappnella cartella dell’app - Controlla la presenza del marcatore
.quarantined(si rifiuta di avviare le app in quarantena) - Controllo di revoca (solo per le app distribuite da NeboAI)
- Verifica della firma (solo per le app distribuite da NeboAI, saltata in sviluppo)
- Convalida del binario (rifiuta link simbolici, script, file non eseguibili e file troppo grandi)
- Rimuove il socket rimasto dall’esecuzione precedente
- Crea la cartella
data/per l’archiviazione in sandbox - Configura file di log per ogni app (
logs/stdout.log,logs/stderr.log) - Avvia il binario con un ambiente ripulito e l’isolamento del gruppo di processi
- Attende che compaia il socket Unix (backoff esponenziale, massimo 10 secondi)
- Si connette tramite gRPC sul socket Unix
- Crea client gRPC specifici per ogni capability in base a
provides - Esegue il controllo di integrità
- 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:
- Includi sempre un campo
actioncome enum di stringhe obbligatorio - Aggiungi un campo
resource(enum di stringhe obbligatorio) solo se il tuo strumento gestisce più tipi di risorse distinti - Tutti gli altri campi sono parametri specifici dell’azione
- La descrizione dell’enum
actiondeve elencare tutte le azioni disponibili
Perché lo STRAP è importante:
- Gli LLM imparano una volta il pattern di instradamento
actione 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
- Nebo chiama
ID()per ottenere l’identificatore univoco del tuo canale - Nebo chiama
Connect()con la configurazione presa dalle impostazioni della tua app - Nebo apre uno stream
Receive(): la tua app invia i messaggi in arrivo ogni volta che un utente scrive al bot - I messaggi in arrivo vengono instradati verso la lane di conversazione principale del dipendente IA
- Quando il dipendente IA vuole inviare un messaggio, Nebo chiama
Send()con la busta del messaggio v1 - 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"
} | Campo | Tipo | Descrizione |
|---|---|---|
message_id | UUID v7 | ID univoco ordinato nel tempo |
channel_id | {type}:{platform_id} | Identificatore del canale instradabile |
sender | object | Identità del bot: nome, ruolo, botId |
text | string | Corpo del messaggio |
attachments | array | File, immagini, audio |
reply_to | UUID v7 | ID del messaggio padre per i thread |
actions | array | Pulsanti/tastiere interattivi |
platform_data | bytes | Dati trasmessi così come sono per le funzioni specifiche della piattaforma |
timestamp | ISO 8601 | Lo 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.
| Campo | Descrizione |
|---|---|
from | ID del dipendente mittente |
to | ID del dipendente destinatario |
topic | Argomento/canale del messaggio |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Corpo del messaggio |
Comportamenti principali:
Registerannuncia questo dipendente IA sulla rete con le sue capabilitySubscribe/Unsubscribegestiscono le iscrizioni agli argomentiReceivetrasmette 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:
| Tipo | Contenuto | Descrizione |
|---|---|---|
"text" | Porzione di testo | Token di testo in streaming |
"tool_call" | JSON | Il modello vuole chiamare uno strumento |
"thinking" | Porzione di testo | Ragionamento esteso |
"error" | Messaggio di errore | Qualcosa è andato storto |
"done" | Vuoto | Lo 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.
| Percorso | Meccanismo | Scopo |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Server di file statici | Serve i file dalla tua cartella ui/ (fallback SPA su index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Inoltra 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:
| File | Dimensione massima | Descrizione |
|---|---|---|
manifest.json | 1 MB | Metadati dell’app |
binary o app | 500 MB | Eseguibile |
signatures.json | 1 MB | Firme Ed25519 |
TOOL.md | 1 MB | Istruzioni 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
- Registra un account NeboAI con
POST /api/v1/owners/register - Accedi per ottenere un token JWT:
POST /api/v1/owners/login - 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
- Scansione automatica: i binari vengono analizzati con VirusTotal
- Revisione amministrativa: il team di NeboAI esamina metadati, manifest e risultati della scansione
- In caso di approvazione: NeboAI firma l’app con Ed25519 e la pubblica
- In caso di rifiuto: ricevi una motivazione e puoi correggere e inviare di nuovo
Tempo di revisione previsto: <24 ore.
Pubblicare aggiornamenti
- Aggiorna la versione dell’app:
PUT /api/v1/developer/apps/{id}con la nuova versione - Carica i nuovi binari per ogni piattaforma
- 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
| Campo | Descrizione |
|---|---|
category | ad es. productivity, communication, developer-tools |
icon | URL dell’icona dell’app |
visibility | public o private |
description | Può essere più lunga e ricca della descrizione nel manifest |
Flusso di sviluppo
Sviluppo locale
Per lo sviluppo locale non serve alcun pacchetto:
- Crea la directory della tua app:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Scrivi il tuo
manifest.jsone il codice - Compila il tuo binario:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo rileva in automatico la nuova cartella (oppure riavvia Nebo)
- 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.logper 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_DATAper 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
| Skill | App | |
|---|---|---|
| Formato | Markdown (SKILL.md) | Binario compilato (.napp) |
| Esecuzione | Inserite nel prompt di sistema | Processo in sandbox tramite gRPC |
| Offrono | Indicazioni di comportamento, metodo | Strumenti, canali, pannelli UI |
| Durata | Limitata alla sessione, scadenza basata su TTL | Sempre in esecuzione |
| Creazione | Scrivi un file markdown | Scrivi, compila, firma, crea il pacchetto |
| Sicurezza | Nessun permesso necessario | Sandbox 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).
| Campo | Obbligatorio | Predefinito | Descrizione |
|---|---|---|---|
name | Sì | — | Identificatore univoco (diventa lo slug) |
description | Sì | — | Descrizione di una riga mostrata nel catalogo delle skill |
version | No | "1.0.0" | Semver per tenere traccia degli aggiornamenti |
author | No | — | Autore della skill |
priority | No | 0 | Più alto = valutato per primo (100+ per le sostituzioni critiche) |
max_turns | No | 4 | Turni di inattività prima della scadenza automatica |
triggers | No | [] | Frasi che attivano in automatico questa skill (corrispondenza di sottostringa, senza distinzione tra maiuscole e minuscole) |
tools | No | [] | Strumenti che questa skill prevede di usare (a titolo informativo) |
dependencies | No | [] | Altre skill che devono essere installate |
tags | No | [] | Per la classificazione e la ricerca |
platform | No | [] | 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:
| Azione | Descrizione | Esempio |
|---|---|---|
catalog | Elenca tutte le skill disponibili | skill(action: "catalog") |
load | Attiva per questa sessione | skill(name: "code-review", action: "load") |
unload | Disattiva una skill | skill(name: "code-review", action: "unload") |
create | Crea una nuova skill su disco | skill(action: "create", content: "...") |
update | Aggiorna una skill esistente | skill(name: "my-skill", action: "update", content: "...") |
delete | Elimina una skill dal disco | skill(name: "my-skill", action: "delete") |
Scrivere buone skill
Un buon modello di skill contiene:
- Un titolo chiaro: dice al dipendente IA in quale modalità si trova
- Principi fondamentali: le regole di comportamento non negoziabili
- Metodo: l’approccio passo passo per i casi più comuni
- Esempi: schemi concreti di messaggio dell’utente e risposta
- 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:
| Skill | Priorità | Descrizione |
|---|---|---|
onboarding | 100 | Benvenuto ai nuovi utenti e raccolta del profilo |
best-friend | 50 | Skill di personalità: informale, leale, parla chiaro |
debugging | 25 | Metodo di debug sistematico |
api-design | 15 | Buone pratiche di progettazione di API RESTful |
code-review | 10 | Revisione del codice strutturata con livelli di gravità |
database-expert | 10 | Progettazione di database, query, ottimizzazione |
git-workflow | 10 | Branch Git, commit, flussi di lavoro delle PR |
security-audit | 10 | Analisi 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.
| File | Servizio | RPC principali |
|---|---|---|
v0/common.proto | (solo messaggi) | 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 |
Ogni servizio include le RPC HealthCheck e Configure. L’SDK le gestisce entrambe in automatico.
Tipi proto dei canali
| Tipo di messaggio | Descrizione |
|---|---|
ChannelSendRequest | Busta del messaggio in uscita con message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID del messaggio della piattaforma per i thread |
InboundMessage | Busta del messaggio in arrivo con tutti i campi comuni + timestamp |
MessageSender | Identità del bot (name, role, botId), arricchita dal broker |
Attachment | Allegato file/immagine/audio (type, url, filename, size) |
MessageAction | Azione 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».