NeboAI
NeboAI
Commencer

Créez des applications pour Nebo

Donnez de nouveaux super-pouvoirs à votre IA. Outils, canaux, passerelles, panneaux d'interface : tout ce que vous pouvez imaginer, compilé en binaire natif.

Présentation

Ce qu'est Nebo

Nebo est un assistant IA personnel pour ordinateur : un employé IA toujours actif qui gère votre vie numérique. Voyez Nebo comme vous voyez un smartphone : une plateforme puissante qui devient révolutionnaire grâce à ses applications.

À lui seul, Nebo est un employé IA compétent, doté de mémoire, de planification, de navigation web, de gestion de fichiers et d'un accès au shell. Mais ce qui change vraiment tout, ce sont les applications. Tout comme la puissance d'un smartphone vient de son écosystème d'applications, celle de Nebo vient des applications qui étendent ce qu'il sait faire.

Ce que sont les applications

Les applications Nebo sont des unités autonomes et précompilées aux fonctionnalités remarquables. Chaque application donne à Nebo un nouveau super-pouvoir : gestion d'agenda, tri des e-mails, suivi de projets, domotique, analyse financière, tout ce qu'un développeur peut imaginer.

Les applications offrent une puissance remarquable en toute sécurité. Chaque application s'exécute dans un bac à sable avec des autorisations refusées par défaut. Elle ne peut accéder qu'à ce que son manifeste déclare et que l'utilisateur approuve.

L'interface est 100 % conversationnelle. Les utilisateurs n'interagissent pas avec les applications via des écrans ou des tableaux de bord séparés. Ils parlent à Nebo, et Nebo utilise les outils de l'application pour faire le travail. « Qu'est-ce que j'ai à l'agenda demain ? » : Nebo appelle l'application d'agenda. « Crée une réunion avec Sarah à 15 h » : Nebo appelle l'application d'agenda. L'utilisateur ne quitte jamais la conversation.

Les applications peuvent, en option, fournir une interface de paramètres : un panneau de configuration qui s'ouvre dans la fenêtre de navigateur intégrée de Nebo. C'est là que les utilisateurs saisissent leurs clés d'API, activent des fonctionnalités et configurent l'application. L'interface de paramètres est pilotée par le tableau settings du manifeste (Nebo génère le formulaire automatiquement), ou l'application peut fournir sa propre interface entièrement personnalisée via la capacité ui.

Les applications remplacent et étendent les capacités intégrées de Nebo. Nebo est livré avec des outils de base de la plateforme (accès à l'agenda local, captures d'écran, etc.). Lorsque vous installez une application d'agenda, elle remplace l'outil d'agenda intégré et en devient un sur-ensemble : local + cloud + agrégation + vérification des disponibilités.

Politique de binaires compilés uniquement

Nebo applique une politique stricte : uniquement des binaires compilés. Toutes les applications doivent être des exécutables natifs compilés.

StatutLangages
Pris en chargeGo (recommandé), Rust, C/C++, Zig
RefusésPython, Node.js, Ruby, Java, .NET, scripts shell

Justification :

  • Prévention de l'auto-modification par l'IA : un employé IA ayant accès au shell pourrait modifier le comportement d'un script interprété pendant son exécution. Les binaires compilés sont immuables une fois signés.
  • Intégrité des signatures : les signatures Ed25519 couvrent les octets bruts du binaire. Un binaire signé ne peut pas être modifié sans invalider la signature.
  • Application du bac à sable : la validation du format binaire (octets magiques ELF/Mach-O/PE) est un contrôle rapide et fiable.

Démarrage rapide

Installer le SDK

Les SDK officiels gèrent toute la configuration du serveur gRPC, la gestion des signaux et le pont de protocole. Il vous suffit d'implémenter les interfaces de gestionnaire.

Go (recommandé) :

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

Rust (bientôt disponible) :

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

C/C++ (bientôt disponible) :

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

Structure du répertoire d'une application

Les applications se trouvent dans le sous-répertoire apps/ de votre répertoire de données 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)

Liste de contrôle d'une application minimale

  1. Créez manifest.json avec id, name, version, provides
  2. Rédigez TOOL.md pour décrire comment l'employé IA doit utiliser votre outil
  3. Installez le SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Implémentez l'interface de gestionnaire de votre capacité (ToolHandler, ChannelHandler, etc.)
  5. Enregistrez le gestionnaire et appelez app.Run()
  6. Compilez un binaire natif (go build -o binary .)
  7. Placez le binaire, manifest.json et TOOL.md dans le répertoire apps/<your-app-id>/
  8. Nebo le détecte et le lance automatiquement

Configuration

manifest.json

Chaque application nécessite 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
        }
    ]
}

Champs obligatoires :

ChampDescription
idIdentifiant en nom de domaine inversé (par ex. com.mycompany.myapp)
nameNom lisible
versionChaîne semver
providesAu moins une capacité (voir ci-dessous)

Champs facultatifs :

ChampPar défautDescription
runtime"local""local" ou "remote"
protocol"grpc"Seul "grpc" est pris en charge
permissions[]Ce à quoi l'application doit accéder
description""Affiché dans l'interface
settings[]Paramètres configurables (affichés dans l'interface des paramètres)
oauth[]Exigences du fournisseur OAuth (voir la section OAuth ci-dessous)

Capacités

Déclarez ce que votre application fournit :

CapacitéService gRPCDescription
gatewayGatewayServiceRoutage des modèles LLM
tool:<name>ToolServiceUn outil nommé pour l'employé IA
channel:<name>ChannelServiceUn canal de messagerie
commCommServiceCommunication entre employés IA
uiUIServiceInterface personnalisée avec proxy HTTP
scheduleScheduleServicePlanification personnalisée
visionToolServiceTraitement de la vision
browserToolServiceAutomatisation du navigateur

Une application peut fournir plusieurs capacités. Par exemple, une application peut fournir à la fois un outil et un panneau d'interface.

Autorisations

Les autorisations contrôlent ce à quoi l'application peut accéder. Tout est refusé par défaut : si ce n'est pas déclaré, l'application ne peut pas l'utiliser.

PréfixeExemplesDescription
network:network:outbound, network:*Accès au réseau
filesystem:filesystem:read, filesystem:writeAccès au système de fichiers
memory:memory:read, memory:writeAccès à la mémoire de l'employé IA
session:session:readSessions de conversation
tool:tool:shell, tool:fileUtiliser d'autres outils
shell:shell:execExécution de commandes shell
channel:channel:send, channel:*Opérations sur les canaux
comm:comm:send, comm:*Communication entre employés IA
model:model:chatAccès aux modèles d'IA
user:user:tokenRecevoir le JWT de l'utilisateur dans les requêtes
schedule:schedule:createGestion des tâches cron
database:database:queryAccès à la base de données
storage:storage:read, storage:writeStockage persistant
context:context:readAccès au contexte de l'employé IA
subagent:subagent:spawnOpérations sur les sous-agents
lane:lane:enqueueOpérations sur les voies
notification:notification:sendNotifications push
embedding:embedding:searchAccès aux embeddings vectoriels
skill:skill:invokeAppel de skills
advisor:advisor:consultAccès au système de conseillers
mcp:mcp:connectAccès aux serveurs MCP
voice:voice:recordAccès à la voix et à l'audio
browser:browser:navigateAutomatisation du navigateur
oauth:oauth:google, oauth:*Accès aux jetons OAuth
settings:settings:readAccès aux paramètres
capability:capability:registerEnregistrement des capacités

Les autorisations avec caractère générique sont prises en charge : network:* correspond à toute vérification d'autorisation network:.

Paramètres

Les paramètres apparaissent dans l'interface de Nebo, dans le panneau de paramètres de l'application. Nebo les stocke dans la base de données et les envoie à votre application via le RPC Configure lorsqu'ils changent.

Votre schéma de paramètres est inclus dans la fiche de l'application sur la boutique NeboAI. Les applications dont des paramètres obligatoires ne sont pas configurés affichent un badge « Configuration requise » dans l'interface.

TypeDescription
textChamp de texte sur une ligne
passwordChamp de texte masqué
toggleInterrupteur booléen activé/désactivé
selectListe déroulante avec options prédéfinies
numberChamp numérique
urlChamp d'URL avec validation
{
    "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"}
    ]
}

Exigences OAuth

Les applications peuvent déclarer des exigences de fournisseur OAuth. Le courtier OAuth de Nebo gère tout le flux : les applications reçoivent automatiquement les jetons via le RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
ChampDescription
providerFournisseur OAuth : "google", "microsoft", "github"
scopesTableau des scopes OAuth dont l'application a besoin

Lorsque l'utilisateur installe l'application, Nebo lui demande d'autoriser les scopes OAuth requis. L'application reçoit les jetons actualisés via le RPC Configure sans gérer elle-même le flux OAuth.

Variables d'environnement

Le processus de votre application reçoit un environnement assaini. Tous les secrets sont supprimés. Vous obtenez :

VariableValeur
NEBO_APP_DIRRépertoire d'installation de l'application
NEBO_APP_SOCKChemin du socket Unix à créer
NEBO_APP_IDID de l'application issu du manifeste
NEBO_APP_NAMENom de l'application issu du manifeste
NEBO_APP_VERSIONVersion de l'application issue du manifeste
NEBO_APP_DATAChemin du répertoire data/ de l'application
PATHPATH du système (transmis tel quel)
HOMERépertoire personnel de l'utilisateur (transmis tel quel)
TMPDIRRépertoire temporaire (transmis tel quel)

Important : votre binaire doit créer un serveur gRPC à l'écoute sur le socket Unix indiqué par NEBO_APP_SOCK. Nebo attend jusqu'à 10 secondes que ce socket apparaisse.

Séquence de lancement d'une application

  1. Nebo lit manifest.json et le valide
  2. Trouve l'exécutable binary ou app dans le répertoire de l'application
  3. Vérifie la présence du marqueur .quarantined (refuse de lancer les applications en quarantaine)
  4. Vérification de révocation (applications distribuées par NeboAI uniquement)
  5. Vérification de signature (applications distribuées par NeboAI uniquement, ignorée en mode développement)
  6. Validation du binaire (refuse les liens symboliques, les scripts, les fichiers non exécutables et les fichiers trop volumineux)
  7. Nettoie le socket obsolète de l'exécution précédente
  8. Crée le répertoire data/ pour le stockage en bac à sable
  9. Configure des fichiers journaux par application (logs/stdout.log, logs/stderr.log)
  10. Lance le binaire avec un environnement assaini et l'isolation du groupe de processus
  11. Attend l'apparition du socket Unix (backoff exponentiel, 10 secondes maximum)
  12. Se connecte via gRPC sur le socket Unix
  13. Crée des clients gRPC propres à chaque capacité selon provides
  14. Exécute un contrôle d'intégrité
  15. Enregistre les capacités auprès de l'employé IA (outils, passerelle, comm, etc.)

Applications d'outil

Déclarez "provides": ["tool:my_tool_name"] dans votre manifeste.

Le modèle STRAP

Toutes les applications d'outil Nebo doivent utiliser le STRAP (Single Tool Resource Action Pattern) pour leur schéma et le routage de leur exécution. C'est le même modèle que Nebo utilise en interne pour regrouper plus de 35 outils individuels en 4 outils par domaine, ce qui réduit d'environ 80 % la charge de contexte du LLM.

Idée centrale : au lieu d'enregistrer plusieurs outils (get_events, check_availability, suggest_slots), enregistrez UN seul outil avec des champs action (et éventuellement resource) qui orientent vers le bon gestionnaire.

Exemple à une seule ressource (agenda) :

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

Exemple à plusieurs ressources (gestionnaire de projets) :

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

Règles du schéma :

  1. Incluez toujours un champ action sous forme d'énumération de chaînes obligatoire
  2. Ajoutez un champ resource (énumération de chaînes obligatoire) uniquement si votre outil gère plusieurs types de ressources distincts
  3. Tous les autres champs sont des paramètres propres à chaque action
  4. La description de l'énumération action doit lister toutes les actions disponibles

Pourquoi STRAP est important :

  • Les LLM apprennent une seule fois le modèle de routage par action et le généralisent à toutes les opérations
  • Les définitions d'outils consomment environ 6 % du contexte : STRAP réduit cela de 80 %
  • Les nouvelles opérations ne sont que des ajouts à l'énumération, pas de nouveaux enregistrements d'outils
  • Fonctionne de la même façon avec les modèles hébergés et locaux

Exemple Go — outil calculatrice

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": []
}

Compiler et installer :

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/

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

Exemple 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;
}

Applications de canal

Déclarez "provides": ["channel:my_channel"] et "permissions": ["channel:send"].

Les applications de canal relient des plateformes de messagerie externes (Telegram, Discord, Slack, etc.) à l'employé IA de Nebo. Lorsqu'un utilisateur envoie un message sur la plateforme externe, votre application le transmet en flux à Nebo via Receive. Lorsque l'employé IA veut répondre, Nebo appelle la méthode Send de votre application.

Fonctionnement

  1. Nebo appelle ID() pour obtenir l'identifiant unique de votre canal
  2. Nebo appelle Connect() avec la configuration issue des paramètres de votre application
  3. Nebo ouvre un flux Receive() : votre application envoie les messages entrants chaque fois qu'un utilisateur écrit au bot
  4. Les messages entrants sont acheminés vers la voie de conversation principale de l'employé IA
  5. Lorsque l'employé IA veut envoyer un message, Nebo appelle Send() avec l'enveloppe de message v1
  6. À l'arrêt, Nebo appelle Disconnect()

Enveloppe de message v1

Tous les messages de canal, entrants comme sortants, utilisent l'enveloppe de message commune :

{
  "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"
}
ChampTypeDescription
message_idUUID v7ID unique ordonné dans le temps
channel_id{type}:{platform_id}Identifiant de canal routable
senderobjectIdentité du bot : nom, rôle, botId
textstringCorps du message
attachmentsarrayFichiers, images, audio
reply_toUUID v7ID du message parent pour les fils de discussion
actionsarrayBoutons et claviers interactifs
platform_databytesTransmission opaque pour les fonctionnalités propres à chaque plateforme
timestampISO 8601Défini par l'éditeur

Conception à deux niveaux : les champs communs (texte, pièces jointes, reply_to, actions) couvrent 90 % des messages initiés par un employé. Les fonctionnalités propres à chaque plateforme vont dans platform_data : votre plugin les convertit depuis et vers le format natif de la plateforme.

Flux de conversation

Les messages de canal sont acheminés via des flux de conversation propres à chaque canal, pour les isoler :

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

Exemple Go — canal 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
        }
    ]
}

Autres capacités

Application comm

Déclarez "provides": ["comm"] et "permissions": ["comm:*"]. Les applications comm permettent la communication entre employés IA.

ChampDescription
fromID de l'employé expéditeur
toID de l'employé destinataire
topicSujet ou canal du message
type"message", "mention", "proposal", "command", "info", "task"
contentCorps du message

Comportements clés :

  • Register annonce cet employé IA sur le réseau avec ses capacités
  • Subscribe/Unsubscribe gèrent les abonnements aux sujets
  • Receive transmet en flux les messages entrants (streaming côté serveur, comme pour les canaux)
  • Une seule application comm peut être active à la fois

Application passerelle

Une application passerelle achemine les requêtes LLM vers les modèles. Déclarez "provides": ["gateway"] et "permissions": ["network:outbound", "user:token"].

GatewayRequest contient les messages, les outils, le prompt système, le nombre maximal de tokens, la température et un UserContext (jeton JWT si l'autorisation user:token est accordée).

Types de GatewayEvent :

TypeContenuDescription
"text"Fragment de texteToken de texte en streaming
"tool_call"JSONLe modèle veut appeler un outil
"thinking"Fragment de texteRéflexion et raisonnement étendus
"error"Message d'erreurUn problème est survenu
"done"VideLe flux est terminé

Application d'interface

Une application d'interface fournit une interface de configuration personnalisée qui s'ouvre dans la fenêtre de navigateur intégrée de Nebo. Déclarez "provides": ["ui"]. Contrairement au formulaire de paramètres automatique (que Nebo génère à partir de vos settings du manifeste), une application d'interface sert son propre frontend HTML/CSS/JS complet.

Votre application inclut un répertoire ui/ contenant des ressources web statiques (HTML, CSS, JS, généralement une SPA avec index.html). Nebo sert ces fichiers directement et relaie les appels d'API vers votre application via gRPC.

CheminMécanismeRôle
GET /api/v1/apps/{id}/ui/*Serveur de fichiers statiquesSert les fichiers de votre répertoire ui/ (repli SPA vers index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCRelaie les requêtes HTTP vers la méthode UIService.HandleRequest() de votre application

Le SDK encapsule un net/http.ServeMux standard : vous écrivez des gestionnaires HTTP Go classiques et le SDK gère automatiquement le pont gRPC.

Exemple Go — interface de tableau de bord :

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

Votre ui/index.html ferait des appels fetch vers /api/v1/apps/com.example.dashboard/api/status, qui sont relayés vers votre gestionnaire mux.

Application de planification

Une application de planification remplace le planificateur cron intégré de Nebo. Déclarez "provides": ["schedule"] et "permissions": ["schedule:create"].

Lorsque votre application de planification démarre, Nebo fait passer toute la planification par votre application au lieu du moteur cron par défaut. Si votre application plante, Nebo revient automatiquement au moteur intégré.

  • Votre application détient l'état des planifications : Nebo ne stocke pas les planifications dans sa propre base de données lorsqu'une application de planification est active
  • CRUD standard : Create, Get, List, Update, Delete, Enable, Disable
  • Triggers est un RPC en streaming côté serveur : votre application envoie un message de déclenchement chaque fois qu'une planification se déclenche
  • Une seule application de planification peut être active à la fois

Applications multi-capacités

Une application peut fournir plusieurs capacités. Par exemple, une application de tableau de bord avec à la fois un outil et une interface :

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

Empaquetage

Format .napp

Pour la distribuer via NeboAI, empaquetez votre application sous forme de fichier .napp (une archive tar.gz) :

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

Fichiers obligatoires :

FichierTaille max.Description
manifest.json1 MBMétadonnées de l'application
binary ou app500 MBExécutable
signatures.json1 MBSignatures Ed25519
TOOL.md1 MBInstructions de l'outil pour l'employé IA

Règles de sécurité lors de l'extraction :

  • Pas de traversée de chemin (../ refusé)
  • Pas de liens symboliques (refusés)
  • Pas de chemins absolus (refusés)
  • Seuls les noms de fichiers autorisés sont acceptés

Signatures

NeboAI signe les applications avec Ed25519. Le format 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 mode développement (aucune URL NeboAI configurée), la vérification des signatures est entièrement ignorée. Vous n'avez pas besoin de signatures.json pour le développement local.

Publication

Une fois que votre application fonctionne en local, publiez-la via NeboAI pour la distribuer à tous les utilisateurs de Nebo.

Configuration du compte développeur

  1. Créez un compte NeboAI via POST /api/v1/owners/register
  2. Connectez-vous pour obtenir un jeton JWT : POST /api/v1/owners/login
  3. Créez un compte développeur : POST /api/v1/developer/accounts

Processus de soumission

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

Étape 1 : créer l'application

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"
  }'

Étape 2 : téléverser les binaires par plateforme

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"

Téléversez un binaire par plateforme : darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Étape 3 : soumettre pour examen

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

Processus d'examen

  1. Analyse automatique : les binaires sont analysés via VirusTotal
  2. Examen par un administrateur : l'équipe NeboAI examine les métadonnées, le manifeste et les résultats de l'analyse
  3. En cas d'approbation : NeboAI signe l'application avec Ed25519 et la publie
  4. En cas de refus : vous recevez un motif et pouvez corriger puis soumettre à nouveau

Délai d'examen visé : <24 heures.

Publier des mises à jour

  1. Mettez à jour la version de l'app : PUT /api/v1/developer/apps/{id} avec la nouvelle version
  2. Téléversez de nouveaux binaires pour chaque plateforme
  3. Soumettez à nouveau pour examen

Chaque mise à jour passe par le même processus d'examen. Les versions précédentes restent disponibles jusqu'à l'approbation de la nouvelle version.

Métadonnées de la boutique

ChampDescription
categorypar ex. productivity, communication, developer-tools
iconURL de l'icône de l'application
visibilitypublic ou private
descriptionPeut être plus longue et plus riche que la description du manifeste

Flux de développement

Développement local

Aucun empaquetage n'est nécessaire pour le développement local :

  1. Créez le répertoire de votre app :
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Rédigez votre manifest.json et votre code
  3. Compilez votre binaire :
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo détecte automatiquement le nouveau répertoire (ou redémarrez Nebo)
  5. Après une modification du code, recompilez le binaire : l'observateur de fichiers redémarrera l'application

Consulter les journaux

Les sorties stdout/stderr de l'application sont enregistrées dans des fichiers journaux par application :

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

Données persistantes

Utilisez le répertoire data/ (également disponible via la variable d'environnement NEBO_APP_DATA) pour tous les fichiers que votre application doit conserver. Ce répertoire est conservé lors des mises à jour et de la mise en quarantaine de l'application.

Conseils de débogage

  • Si votre application ne démarre pas, consultez logs/stderr.log pour voir les erreurs
  • Assurez-vous que le binaire est exécutable (chmod +x binary)
  • Vérifiez que vous écoutez bien sur le chemin de socket Unix indiqué par NEBO_APP_SOCK
  • Le socket doit être prêt dans les 10 secondes suivant le lancement
  • Utilisez NEBO_APP_DATA pour le stockage, pas des chemins codés en dur
  • Écrivez sur stderr pour les journaux de débogage (enregistrés dans logs/stderr.log)

Vérification

# 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

Désinstallation

nebo apps uninstall com.example.myapp

Skills

Ce que sont les skills

Les skills sont des ensembles d'instructions qui façonnent le comportement de Nebo pendant une conversation. Lorsqu'un skill est actif, son contenu est injecté directement dans le prompt système : il oriente le ton, la méthode, l'expertise métier et l'usage des outils de l'employé IA pendant cette session.

Les skills ne sont pas du code. Ce sont des documents markdown avec des métadonnées YAML. Pas de compilation, pas de binaire, pas de gRPC. Un skill, c'est un fichier SKILL.md dans un répertoire. C'est tout.

Les skills sont contextuels et temporaires. Ils s'activent quand c'est pertinent (par correspondance avec un déclencheur ou par chargement manuel), restent actifs pendant quelques tours et expirent lorsqu'ils ne sont plus utiles. Le contexte de l'employé IA reste ainsi léger : seules les consignes utiles à cet instant figurent dans le prompt.

Les skills complètent les applications. Les applications fournissent des capacités exécutables (outils, canaux, passerelles). Les skills fournissent des consignes d'orchestration : comment utiliser ces outils efficacement. Une application d'agenda donne à Nebo la capacité de lire et d'écrire des événements. Un skill « préparation de réunion » indique à Nebo comment préparer les réunions en combinant cette application d'agenda, les e-mails et la recherche web.

Skills ou applications

SkillsApplications
FormatMarkdown (SKILL.md)Binaire compilé (.napp)
ExécutionInjecté dans le prompt systèmeProcessus en bac à sable via gRPC
FournitConsignes de comportement, méthodeOutils, canaux, panneaux d'interface
Durée de vieLimité à la session, expiration selon un TTLToujours en cours d'exécution
CréationRédiger un fichier markdownÉcrire, compiler, signer, empaqueter
SécuritéAucune autorisation nécessaireBac à sable avec refus par défaut

Démarrage rapide

Créez un répertoire dans votre dossier de skills Nebo avec un fichier SKILL.md :

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

Rédigez 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 surveille le répertoire des skills avec fsnotify. Votre skill est disponible immédiatement, sans redémarrage. Dites quelque chose qui correspond à un déclencheur, et il s'active automatiquement.

Ou demandez directement à Nebo : « Crée un skill pour rédiger des articles de blog ». Nebo écrira le fichier SKILL.md pour vous.

Format de SKILL.md

Chaque skill est un seul fichier SKILL.md en deux parties : un en-tête YAML entre des marqueurs ---, et un corps en markdown (les instructions réellement injectées dans le prompt système).

ChampObligatoirePar défautDescription
nameOui—Identifiant unique (devient le slug)
descriptionOui—Description d'une ligne affichée dans le catalogue des skills
versionNon"1.0.0"Semver pour suivre les mises à jour
authorNon—Auteur du skill
priorityNon0Plus élevé = évalué en premier (100+ pour les priorités critiques)
max_turnsNon4Nombre de tours d'inactivité avant l'expiration automatique
triggersNon[]Expressions qui activent automatiquement ce skill (correspondance de sous-chaîne, insensible à la casse)
toolsNon[]Outils que ce skill prévoit d'utiliser (à titre indicatif)
dependenciesNon[]Autres skills qui doivent être installés
tagsNon[]Pour le classement et la découverte
platformNon[]Plateformes prises en charge : macos, linux, windows (vide = toutes)

Comment les skills s'activent

Les skills suivent un modèle d'activation en deux phases : suggestion, puis appel.

Phase 1 : correspondance des déclencheurs : chaque fois qu'un utilisateur envoie un message, Nebo examine tous les skills enregistrés à la recherche de déclencheurs correspondants. Les skills correspondants apparaissent sous forme de suggestions dans le prompt système. L'employé IA voit la suggestion et décide s'il appelle le skill.

Phase 2 : appel : l'employé IA appelle un skill ainsi :

skill(name: "code-review")

Cela renvoie le modèle SKILL.md complet comme résultat de l'outil, enregistre l'appel et réinjecte le modèle dans le prompt système lors des tours suivants.

TTL et expiration :

  • Skills activés automatiquement : 4 tours d'inactivité (configurable via max_turns)
  • Skills chargés manuellement : 6 tours d'inactivité
  • Un nouvel appel réinitialise le minuteur
  • Limite stricte : 4 skills actifs au maximum par session
  • Budget de tokens : le contenu cumulé des skills actifs est limité à 16 000 caractères

Gérer les skills

L'employé IA peut gérer les skills avec l'outil skill :

ActionDescriptionExemple
catalogLister tous les skills disponiblesskill(action: "catalog")
loadActiver pour cette sessionskill(name: "code-review", action: "load")
unloadDésactiver un skillskill(name: "code-review", action: "unload")
createCréer un nouveau skill sur le disqueskill(action: "create", content: "...")
updateMettre à jour un skill existantskill(name: "my-skill", action: "update", content: "...")
deleteSupprimer un skill du disqueskill(name: "my-skill", action: "delete")

Écrire de bons skills

Un bon modèle de skill comporte :

  1. Un titre clair : il indique à l'employé IA dans quel mode il se trouve
  2. Des principes fondamentaux : les règles de comportement non négociables
  3. Une méthode : une démarche pas à pas pour les situations courantes
  4. Des exemples : des cas concrets de message utilisateur et de réponse
  5. Des contre-exemples : ce qu'il ne faut PAS faire (les modèles apprennent bien des exemples négatifs)

Astuce : chaque skill doit bien faire une seule chose. Ne créez pas un skill « programmation générale » : créez code-review, debugging et api-design comme skills séparés. L'employé IA peut en avoir plusieurs actifs en même temps.

Skills intégrés

Nebo est livré avec des skills intégrés qui couvrent les usages courants :

SkillPrioritéDescription
onboarding100Accueil des nouveaux utilisateurs et collecte de leur profil
best-friend50Skill de personnalité : décontracté, loyal, franc
debugging25Méthode de débogage systématique
api-design15Bonnes pratiques de conception d'API RESTful
code-review10Revue de code structurée avec niveaux de gravité
database-expert10Conception de bases de données, requêtes, optimisation
git-workflow10Branches Git, commits, workflows de PR
security-audit10Analyse de sécurité et détection des vulnérabilités

Ils servent à la fois de valeurs par défaut utiles et d'implémentations de référence pour créer vos propres skills.

Référence

Fichiers proto

Les fichiers proto se trouvent dans proto/apps/v0/. Les SDK sont livrés avec du code prégénéré : vous n'avez pas besoin de protoc pour le développement courant.

FichierServiceRPC principaux
v0/common.proto(messages uniquement)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

Chaque service inclut les RPC HealthCheck et Configure. Le SDK gère les deux automatiquement.

Types proto des canaux

Type de messageDescription
ChannelSendRequestEnveloppe de message sortant avec message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID du message sur la plateforme, pour les fils de discussion
InboundMessageEnveloppe de message entrant avec tous les champs communs + horodatage
MessageSenderIdentité du bot (name, role, botId), enrichie par le courtier
AttachmentPièce jointe fichier, image ou audio (type, url, filename, size)
MessageActionAction de bouton ou de clavier interactif (label, callback_id)

Identité et rôles des bots

Les bots Nebo ont un modèle d'identité à trois axes :

  • creature : ce qu'est le bot (archétype) : « Stratège à l'esprit vif », « Chercheur méticuleux »
  • role : sa relation avec l'utilisateur : « Ami », « Directeur des opérations », « Mentor »
  • vibe : son énergie (style de communication) : « Détendu mais avec des opinions », « Chaleureux et encourageant »

Lorsque votre plugin de canal reçoit un message sortant, le champ sender contient le name et le role du bot. Utilisez-les pour formater le nom affiché sur votre plateforme. Le rôle n'est pas un intitulé de poste : il décrit une relation. « Ami », « Fils » et « Mentor » sont des rôles valides, au même titre que « COO » et « DevLead ».