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.
| Statut | Langages |
|---|---|
| Pris en charge | Go (recommandé), Rust, C/C++, Zig |
| Refusés | Python, 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
- Créez
manifest.jsonavecid,name,version,provides - Rédigez
TOOL.mdpour décrire comment l'employé IA doit utiliser votre outil - Installez le SDK (
go get github.com/neboloop/nebo-sdk-go) - Implémentez l'interface de gestionnaire de votre capacité (
ToolHandler,ChannelHandler, etc.) - Enregistrez le gestionnaire et appelez
app.Run() - Compilez un binaire natif (
go build -o binary .) - Placez le binaire, manifest.json et TOOL.md dans le répertoire
apps/<your-app-id>/ - 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 :
| Champ | Description |
|---|---|
id | Identifiant en nom de domaine inversé (par ex. com.mycompany.myapp) |
name | Nom lisible |
version | Chaîne semver |
provides | Au moins une capacité (voir ci-dessous) |
Champs facultatifs :
| Champ | Par défaut | Description |
|---|---|---|
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 gRPC | Description |
|---|---|---|
gateway | GatewayService | Routage des modèles LLM |
tool:<name> | ToolService | Un outil nommé pour l'employé IA |
channel:<name> | ChannelService | Un canal de messagerie |
comm | CommService | Communication entre employés IA |
ui | UIService | Interface personnalisée avec proxy HTTP |
schedule | ScheduleService | Planification personnalisée |
vision | ToolService | Traitement de la vision |
browser | ToolService | Automatisation 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éfixe | Exemples | Description |
|---|---|---|
network: | network:outbound, network:* | Accès au réseau |
filesystem: | filesystem:read, filesystem:write | Accès au système de fichiers |
memory: | memory:read, memory:write | Accès à la mémoire de l'employé IA |
session: | session:read | Sessions de conversation |
tool: | tool:shell, tool:file | Utiliser d'autres outils |
shell: | shell:exec | Exécution de commandes shell |
channel: | channel:send, channel:* | Opérations sur les canaux |
comm: | comm:send, comm:* | Communication entre employés IA |
model: | model:chat | Accès aux modèles d'IA |
user: | user:token | Recevoir le JWT de l'utilisateur dans les requêtes |
schedule: | schedule:create | Gestion des tâches cron |
database: | database:query | Accès à la base de données |
storage: | storage:read, storage:write | Stockage persistant |
context: | context:read | Accès au contexte de l'employé IA |
subagent: | subagent:spawn | Opérations sur les sous-agents |
lane: | lane:enqueue | Opérations sur les voies |
notification: | notification:send | Notifications push |
embedding: | embedding:search | Accès aux embeddings vectoriels |
skill: | skill:invoke | Appel de skills |
advisor: | advisor:consult | Accès au système de conseillers |
mcp: | mcp:connect | Accès aux serveurs MCP |
voice: | voice:record | Accès à la voix et à l'audio |
browser: | browser:navigate | Automatisation du navigateur |
oauth: | oauth:google, oauth:* | Accès aux jetons OAuth |
settings: | settings:read | Accès aux paramètres |
capability: | capability:register | Enregistrement 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.
| Type | Description |
|---|---|
text | Champ de texte sur une ligne |
password | Champ de texte masqué |
toggle | Interrupteur booléen activé/désactivé |
select | Liste déroulante avec options prédéfinies |
number | Champ numérique |
url | Champ 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"]
}
]
} | Champ | Description |
|---|---|
provider | Fournisseur OAuth : "google", "microsoft", "github" |
scopes | Tableau 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 :
| Variable | Valeur |
|---|---|
NEBO_APP_DIR | Répertoire d'installation de l'application |
NEBO_APP_SOCK | Chemin du socket Unix à créer |
NEBO_APP_ID | ID de l'application issu du manifeste |
NEBO_APP_NAME | Nom de l'application issu du manifeste |
NEBO_APP_VERSION | Version de l'application issue du manifeste |
NEBO_APP_DATA | Chemin du répertoire data/ de l'application |
PATH | PATH du système (transmis tel quel) |
HOME | Répertoire personnel de l'utilisateur (transmis tel quel) |
TMPDIR | Ré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
- Nebo lit
manifest.jsonet le valide - Trouve l'exécutable
binaryouappdans le répertoire de l'application - Vérifie la présence du marqueur
.quarantined(refuse de lancer les applications en quarantaine) - Vérification de révocation (applications distribuées par NeboAI uniquement)
- Vérification de signature (applications distribuées par NeboAI uniquement, ignorée en mode développement)
- Validation du binaire (refuse les liens symboliques, les scripts, les fichiers non exécutables et les fichiers trop volumineux)
- Nettoie le socket obsolète de l'exécution précédente
- Crée le répertoire
data/pour le stockage en bac à sable - Configure des fichiers journaux par application (
logs/stdout.log,logs/stderr.log) - Lance le binaire avec un environnement assaini et l'isolation du groupe de processus
- Attend l'apparition du socket Unix (backoff exponentiel, 10 secondes maximum)
- Se connecte via gRPC sur le socket Unix
- Crée des clients gRPC propres à chaque capacité selon
provides - Exécute un contrôle d'intégrité
- 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 :
- Incluez toujours un champ
actionsous forme d'énumération de chaînes obligatoire - Ajoutez un champ
resource(énumération de chaînes obligatoire) uniquement si votre outil gère plusieurs types de ressources distincts - Tous les autres champs sont des paramètres propres à chaque action
- La description de l'énumération
actiondoit lister toutes les actions disponibles
Pourquoi STRAP est important :
- Les LLM apprennent une seule fois le modèle de routage par
actionet 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
- Nebo appelle
ID()pour obtenir l'identifiant unique de votre canal - Nebo appelle
Connect()avec la configuration issue des paramètres de votre application - Nebo ouvre un flux
Receive(): votre application envoie les messages entrants chaque fois qu'un utilisateur écrit au bot - Les messages entrants sont acheminés vers la voie de conversation principale de l'employé IA
- Lorsque l'employé IA veut envoyer un message, Nebo appelle
Send()avec l'enveloppe de message v1 - À 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"
} | Champ | Type | Description |
|---|---|---|
message_id | UUID v7 | ID unique ordonné dans le temps |
channel_id | {type}:{platform_id} | Identifiant de canal routable |
sender | object | Identité du bot : nom, rôle, botId |
text | string | Corps du message |
attachments | array | Fichiers, images, audio |
reply_to | UUID v7 | ID du message parent pour les fils de discussion |
actions | array | Boutons et claviers interactifs |
platform_data | bytes | Transmission opaque pour les fonctionnalités propres à chaque plateforme |
timestamp | ISO 8601 | Dé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.
| Champ | Description |
|---|---|
from | ID de l'employé expéditeur |
to | ID de l'employé destinataire |
topic | Sujet ou canal du message |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Corps du message |
Comportements clés :
Registerannonce cet employé IA sur le réseau avec ses capacitésSubscribe/Unsubscribegèrent les abonnements aux sujetsReceivetransmet 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 :
| Type | Contenu | Description |
|---|---|---|
"text" | Fragment de texte | Token de texte en streaming |
"tool_call" | JSON | Le modèle veut appeler un outil |
"thinking" | Fragment de texte | Réflexion et raisonnement étendus |
"error" | Message d'erreur | Un problème est survenu |
"done" | Vide | Le 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.
| Chemin | Mécanisme | Rôle |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Serveur de fichiers statiques | Sert les fichiers de votre répertoire ui/ (repli SPA vers index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Relaie 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 Triggersest 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 :
| Fichier | Taille max. | Description |
|---|---|---|
manifest.json | 1 MB | Métadonnées de l'application |
binary ou app | 500 MB | Exécutable |
signatures.json | 1 MB | Signatures Ed25519 |
TOOL.md | 1 MB | Instructions 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
- Créez un compte NeboAI via
POST /api/v1/owners/register - Connectez-vous pour obtenir un jeton JWT :
POST /api/v1/owners/login - 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
- Analyse automatique : les binaires sont analysés via VirusTotal
- Examen par un administrateur : l'équipe NeboAI examine les métadonnées, le manifeste et les résultats de l'analyse
- En cas d'approbation : NeboAI signe l'application avec Ed25519 et la publie
- 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
- Mettez à jour la version de l'app :
PUT /api/v1/developer/apps/{id}avec la nouvelle version - Téléversez de nouveaux binaires pour chaque plateforme
- 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
| Champ | Description |
|---|---|
category | par ex. productivity, communication, developer-tools |
icon | URL de l'icône de l'application |
visibility | public ou private |
description | Peut ê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 :
- Créez le répertoire de votre app :
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Rédigez votre
manifest.jsonet votre code - Compilez votre binaire :
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo détecte automatiquement le nouveau répertoire (ou redémarrez Nebo)
- 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.logpour 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_DATApour 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
| Skills | Applications | |
|---|---|---|
| Format | Markdown (SKILL.md) | Binaire compilé (.napp) |
| Exécution | Injecté dans le prompt système | Processus en bac à sable via gRPC |
| Fournit | Consignes de comportement, méthode | Outils, canaux, panneaux d'interface |
| Durée de vie | Limité à la session, expiration selon un TTL | Toujours en cours d'exécution |
| Création | Rédiger un fichier markdown | Écrire, compiler, signer, empaqueter |
| Sécurité | Aucune autorisation nécessaire | Bac à 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).
| Champ | Obligatoire | Par défaut | Description |
|---|---|---|---|
name | Oui | — | Identifiant unique (devient le slug) |
description | Oui | — | Description d'une ligne affichée dans le catalogue des skills |
version | Non | "1.0.0" | Semver pour suivre les mises à jour |
author | Non | — | Auteur du skill |
priority | Non | 0 | Plus élevé = évalué en premier (100+ pour les priorités critiques) |
max_turns | Non | 4 | Nombre de tours d'inactivité avant l'expiration automatique |
triggers | Non | [] | Expressions qui activent automatiquement ce skill (correspondance de sous-chaîne, insensible à la casse) |
tools | Non | [] | Outils que ce skill prévoit d'utiliser (à titre indicatif) |
dependencies | Non | [] | Autres skills qui doivent être installés |
tags | Non | [] | Pour le classement et la découverte |
platform | Non | [] | 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 :
| Action | Description | Exemple |
|---|---|---|
catalog | Lister tous les skills disponibles | skill(action: "catalog") |
load | Activer pour cette session | skill(name: "code-review", action: "load") |
unload | Désactiver un skill | skill(name: "code-review", action: "unload") |
create | Créer un nouveau skill sur le disque | skill(action: "create", content: "...") |
update | Mettre à jour un skill existant | skill(name: "my-skill", action: "update", content: "...") |
delete | Supprimer un skill du disque | skill(name: "my-skill", action: "delete") |
Écrire de bons skills
Un bon modèle de skill comporte :
- Un titre clair : il indique à l'employé IA dans quel mode il se trouve
- Des principes fondamentaux : les règles de comportement non négociables
- Une méthode : une démarche pas à pas pour les situations courantes
- Des exemples : des cas concrets de message utilisateur et de réponse
- 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 :
| Skill | Priorité | Description |
|---|---|---|
onboarding | 100 | Accueil des nouveaux utilisateurs et collecte de leur profil |
best-friend | 50 | Skill de personnalité : décontracté, loyal, franc |
debugging | 25 | Méthode de débogage systématique |
api-design | 15 | Bonnes pratiques de conception d'API RESTful |
code-review | 10 | Revue de code structurée avec niveaux de gravité |
database-expert | 10 | Conception de bases de données, requêtes, optimisation |
git-workflow | 10 | Branches Git, commits, workflows de PR |
security-audit | 10 | Analyse 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.
| Fichier | Service | RPC principaux |
|---|---|---|
v0/common.proto | (messages uniquement) | 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 |
Chaque service inclut les RPC HealthCheck et Configure. Le SDK gère les deux automatiquement.
Types proto des canaux
| Type de message | Description |
|---|---|
ChannelSendRequest | Enveloppe de message sortant avec message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID du message sur la plateforme, pour les fils de discussion |
InboundMessage | Enveloppe de message entrant avec tous les champs communs + horodatage |
MessageSender | Identité du bot (name, role, botId), enrichie par le courtier |
Attachment | Pièce jointe fichier, image ou audio (type, url, filename, size) |
MessageAction | Action 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 ».