NeboAI
NeboAI
Începe

Construiește aplicații pentru Nebo

Dă-i IA tale superputeri noi. Instrumente, canale, gateway-uri, panouri UI — orice îți poți imagina, compilat într-un binar nativ.

Prezentare generală

Ce este Nebo

Nebo este un asistent IA personal pentru desktop — un angajat IA care rulează mereu și îți gestionează viața digitală. Gândește-te la Nebo cum te gândești la un smartphone: o platformă puternică ce devine transformatoare prin aplicațiile ei.

Singur, Nebo este un angajat IA capabil, cu memorie, programare, navigare pe web, gestionare de fișiere și acces la shell. Dar adevărata deblocare sunt aplicațiile. Așa cum puterea unui smartphone vine din ecosistemul lui de aplicații, puterea lui Nebo vine din aplicațiile care extind ce poate face.

Ce sunt aplicațiile

Aplicațiile Nebo sunt unități autonome, precompilate, cu funcționalități incredibile. Fiecare aplicație îi dă lui Nebo o superputere nouă — gestionarea calendarului, trierea e-mailurilor, urmărirea proiectelor, automatizarea casei, analiza financiară — orice își poate imagina un dezvoltator.

Aplicațiile oferă o putere incredibilă într-un mod foarte sigur. Fiecare aplicație rulează într-un sandbox cu permisiuni refuzate implicit. Poate accesa doar ce declară manifestul ei și aprobă utilizatorul.

Interfața este 100% conversațională. Utilizatorii nu interacționează cu aplicațiile prin ecrane sau tablouri de bord separate. Vorbesc cu Nebo, iar Nebo folosește instrumentele aplicației ca să facă lucrurile. „Ce am mâine în calendar?” — Nebo apelează aplicația de calendar. „Creează o întâlnire cu Sarah la 3pm” — Nebo apelează aplicația de calendar. Utilizatorul nu iese niciodată din conversație.

Aplicațiile pot oferi opțional o interfață de setări — un panou de configurare care se deschide în fereastra de browser integrată a lui Nebo. Aici introduc utilizatorii cheile API, activează funcții și configurează aplicația. Interfața de setări e generată din tabloul settings din manifest (Nebo randează formularul automat) sau aplicația își poate oferi propria interfață complet personalizată prin capabilitatea ui.

Aplicațiile înlocuiesc și extind capabilitățile integrate ale lui Nebo. Nebo vine cu instrumente de bază ale platformei (acces local la calendar, capturi de ecran etc.). Când instalezi o aplicație de calendar, aceasta înlocuiește instrumentul de calendar integrat și devine un superset — local + cloud + agregare + verificarea disponibilității.

Politica „doar compilat”

Nebo aplică o politică strictă: doar binare compilate. Toate aplicațiile trebuie să fie executabile native compilate.

StareLimbaje
AcceptateGo (recomandat), Rust, C/C++, Zig
RespinsePython, Node.js, Ruby, Java, .NET, scripturi shell

Motivare:

  • Prevenirea automodificării de către IA — Un angajat IA cu acces la shell ar putea modifica în timpul rulării comportamentul unui script interpretat. Binarele compilate sunt imuabile după semnare.
  • Integritatea semnăturii — Semnăturile Ed25519 acoperă octeții bruți ai binarului. Un binar semnat nu poate fi modificat fără a invalida semnătura.
  • Aplicarea sandboxului — Validarea formatului binar (octeții magici ELF/Mach-O/PE) este o barieră rapidă și sigură.

Început rapid

Instalează SDK-ul

SDK-urile oficiale se ocupă de toată configurarea serverului gRPC, de gestionarea semnalelor și de puntea de protocol. Tu doar implementezi interfețele de handler.

Go (recomandat):

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

Rust (în curând):

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

C/C++ (în curând):

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

Structura directorului aplicației

Aplicațiile stau în subdirectorul apps/ al directorului de date Nebo:

~/Library/Application Support/Nebo/apps/   # macOS
~/.config/nebo/apps/                        # Linux
%AppData%\Nebo\apps\                        # Windows

apps/
  com.example.myapp/
    manifest.json       # Required: app metadata
    binary              # Required: executable (or named "app")
    signatures.json     # Required for NeboAI distribution, optional in dev
    TOOL.md             # Required: tool instructions for the agent
    data/               # Auto-created: app's sandboxed storage
    logs/               # Auto-created: stdout.log, stderr.log
    ui/                 # Optional: static UI assets (HTML/CSS/JS)

Lista de verificare pentru o aplicație minimă

  1. Creează manifest.json cu id, name, version, provides
  2. Scrie TOOL.md, care descrie cum ar trebui să-ți folosească angajatul IA instrumentul
  3. Instalează SDK-ul (go get github.com/neboloop/nebo-sdk-go)
  4. Implementează interfața de handler pentru capabilitatea ta (ToolHandler, ChannelHandler etc.)
  5. Înregistrează handlerul și apelează app.Run()
  6. Construiește un binar nativ (go build -o binary .)
  7. Pune binarul + manifest.json + TOOL.md în directorul apps/<your-app-id>/
  8. Nebo îl descoperă și îl lansează automat

Configurare

manifest.json

Fiecare aplicație are nevoie de 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
        }
    ]
}

Câmpuri obligatorii:

CâmpDescriere
idIdentificator în format de domeniu inversat (de ex., com.mycompany.myapp)
nameNume lizibil pentru oameni
versionȘir Semver
providesCel puțin o capabilitate (vezi mai jos)

Câmpuri opționale:

CâmpImplicitDescriere
runtime"local""local" sau "remote"
protocol"grpc"Doar "grpc" este acceptat
permissions[]La ce are nevoie aplicația de acces
description""Afișat în interfață
settings[]Setări configurabile (randate în interfața Setări)
oauth[]Cerințe privind furnizorul OAuth (vezi secțiunea OAuth de mai jos)

Capabilități

Declară ce oferă aplicația ta:

CapabilitateServiciu gRPCDescriere
gatewayGatewayServiceRutarea modelelor LLM
tool:<name>ToolServiceUn instrument cu nume pentru angajatul IA
channel:<name>ChannelServiceUn canal de mesagerie
commCommServiceComunicare între angajații IA
uiUIServiceInterfață personalizată cu proxy HTTP
scheduleScheduleServiceProgramare personalizată
visionToolServiceProcesare vizuală
browserToolServiceAutomatizarea browserului

O aplicație poate oferi mai multe capabilități. De exemplu, o aplicație poate oferi atât un instrument, cât și un panou UI.

Permisiuni

Permisiunile controlează ce poate accesa aplicația. Refuzat implicit — dacă nu e declarat, aplicația nu o poate folosi.

PrefixExempleDescriere
network:network:outbound, network:*Acces la rețea
filesystem:filesystem:read, filesystem:writeAcces la sistemul de fișiere
memory:memory:read, memory:writeAcces la memoria angajatului IA
session:session:readSesiuni de conversație
tool:tool:shell, tool:fileFolosirea altor instrumente
shell:shell:execExecutarea comenzilor shell
channel:channel:send, channel:*Operațiuni pe canale
comm:comm:send, comm:*Comunicare între angajații IA
model:model:chatAcces la modele IA
user:user:tokenPrimirea JWT-ului utilizatorului în cereri
schedule:schedule:createGestionarea joburilor cron
database:database:queryAcces la baza de date
storage:storage:read, storage:writeStocare persistentă
context:context:readAcces la contextul angajatului IA
subagent:subagent:spawnOperațiuni cu subagenți
lane:lane:enqueueOperațiuni pe benzi
notification:notification:sendNotificări push
embedding:embedding:searchAcces la embeddinguri vectoriale
skill:skill:invokeInvocarea abilităților
advisor:advisor:consultAcces la sistemul de consilieri
mcp:mcp:connectAcces la serverele MCP
voice:voice:recordAcces la voce/audio
browser:browser:navigateAutomatizarea browserului
oauth:oauth:google, oauth:*Acces la tokenurile OAuth
settings:settings:readAcces la setări
capability:capability:registerÎnregistrarea capabilităților

Sunt acceptate permisiunile cu wildcard: network:* corespunde oricărei verificări de permisiune network:.

Setări

Setările apar în interfața Nebo, în panoul de setări al aplicației. Nebo le stochează în baza de date și i le trimite aplicației tale prin RPC-ul Configure când se schimbă.

Schema setărilor tale e inclusă în listarea din magazinul de aplicații NeboAI. Aplicațiile cu setări obligatorii neconfigurate afișează în interfață insigna „Necesită configurare”.

TipDescriere
textCâmp de text pe un singur rând
passwordCâmp de text mascat
toggleComutator boolean pornit/oprit
selectListă derulantă cu opțiuni predefinite
numberCâmp numeric
urlCâmp URL cu validare
{
    "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"}
    ]
}

Cerințe OAuth

Aplicațiile pot declara cerințe privind furnizorul OAuth. Brokerul OAuth al lui Nebo se ocupă de tot fluxul — aplicațiile primesc tokenurile automat prin RPC-ul Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
CâmpDescriere
providerFurnizor OAuth: "google", "microsoft", "github"
scopesTablou cu domeniile OAuth de care are nevoie aplicația

Când utilizatorul instalează aplicația, Nebo îi cere să autorizeze domeniile OAuth necesare. Aplicația primește tokenuri reîmprospătate prin RPC-ul Configure, fără să gestioneze ea însăși fluxul OAuth.

Variabile de mediu

Procesul aplicației tale primește un mediu igienizat. Toate secretele sunt eliminate. Primești:

VariabilăValoare
NEBO_APP_DIRDirectorul de instalare al aplicației
NEBO_APP_SOCKCalea către socketul Unix care trebuie creat
NEBO_APP_IDID-ul aplicației din manifest
NEBO_APP_NAMENumele aplicației din manifest
NEBO_APP_VERSIONVersiunea aplicației din manifest
NEBO_APP_DATACalea către directorul data/ al aplicației
PATHPATH-ul sistemului (transmis mai departe)
HOMEDirectorul home al utilizatorului (transmis mai departe)
TMPDIRDirectorul temporar (transmis mai departe)

Esențial: Binarul tău trebuie să creeze un server gRPC care ascultă pe socketul Unix de la NEBO_APP_SOCK. Nebo așteaptă până la 10 secunde să apară acest socket.

Secvența de lansare a aplicației

  1. Nebo citește manifest.json și îl validează
  2. Găsește executabilul binary sau app în directorul aplicației
  3. Verifică existența marcajului .quarantined (refuză să lanseze aplicațiile aflate în carantină)
  4. Verificarea revocării (doar pentru aplicațiile distribuite de NeboAI)
  5. Verificarea semnăturii (doar pentru aplicațiile distribuite de NeboAI, omisă în modul de dezvoltare)
  6. Validarea binarului (respinge linkurile simbolice, scripturile, fișierele neexecutabile și fișierele prea mari)
  7. Curăță socketul rămas de la rularea anterioară
  8. Creează directorul data/ pentru stocarea în sandbox
  9. Configurează fișiere de jurnal pentru fiecare aplicație (logs/stdout.log, logs/stderr.log)
  10. Pornește binarul cu un mediu igienizat și cu izolarea grupului de procese
  11. Așteaptă să apară socketul Unix (backoff exponențial, maximum 10 secunde)
  12. Se conectează prin gRPC peste socketul Unix
  13. Creează clienți gRPC specifici capabilităților, pe baza provides
  14. Rulează verificarea stării de sănătate
  15. Înregistrează capabilitățile la angajatul IA (instrumente, gateway, comm etc.)

Aplicații de tip instrument

Declară "provides": ["tool:my_tool_name"] în manifest.

Modelul STRAP

Toate aplicațiile Nebo de tip instrument trebuie să folosească STRAP (Single Tool Resource Action Pattern) pentru schemă și pentru rutarea execuției. Este același model pe care Nebo îl folosește intern ca să consolideze peste 35 de instrumente individuale în 4 instrumente de domeniu — reducând cu ~80% încărcarea contextului LLM.

Ideea de bază: În loc să înregistrezi mai multe instrumente (get_events, check_availability, suggest_slots), înregistrezi UN SINGUR instrument cu câmpurile action (și opțional resource) care direcționează către handlerul potrivit.

Exemplu cu o singură resursă (calendar):

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

Exemplu cu mai multe resurse (manager de proiecte):

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

Reguli pentru schemă:

  1. Include întotdeauna un câmp action ca enum de tip șir, obligatoriu
  2. Adaugă un câmp resource (enum de tip șir, obligatoriu) doar dacă instrumentul tău gestionează mai multe tipuri distincte de resurse
  3. Toate celelalte câmpuri sunt parametri specifici acțiunii
  4. Descrierea enumului action ar trebui să enumere toate acțiunile disponibile

De ce contează STRAP:

  • LLM-urile învață o singură dată modelul de rutare action și îl generalizează la toate operațiunile
  • Definițiile instrumentelor consumă ~6% din context — STRAP reduce asta cu 80%
  • Operațiunile noi sunt doar valori noi în enum, nu înregistrări noi de instrumente
  • Funcționează identic cu modelele găzduite și cu cele locale

Exemplu Go — Instrument calculator

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

Construire și instalare:

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/

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

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

Aplicații de tip canal

Declară "provides": ["channel:my_channel"] și "permissions": ["channel:send"].

Aplicațiile de tip canal fac puntea între platformele externe de mesagerie (Telegram, Discord, Slack etc.) și angajatul IA al lui Nebo. Când un utilizator trimite un mesaj pe platforma externă, aplicația ta îl transmite în flux către Nebo prin Receive. Când angajatul IA vrea să răspundă, Nebo apelează Send din aplicația ta.

Cum funcționează

  1. Nebo apelează ID() ca să obțină identificatorul unic al canalului tău
  2. Nebo apelează Connect() cu configurația din setările aplicației tale
  3. Nebo deschide un flux Receive() — aplicația ta trimite mesajele primite ori de câte ori un utilizator îi scrie botului
  4. Mesajele primite sunt direcționate către banda principală de conversație a angajatului IA
  5. Când angajatul IA vrea să trimită un mesaj, Nebo apelează Send() cu plicul de mesaj v1
  6. La oprire, Nebo apelează Disconnect()

Plicul de mesaj v1

Toate mesajele de canal — primite și trimise — folosesc plicul de mesaj comun:

{
  "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"
}
CâmpTipDescriere
message_idUUID v7ID unic ordonat în timp
channel_id{type}:{platform_id}Identificator de canal care poate fi rutat
senderobjectIdentitatea botului — nume, rol, botId
textstringCorpul mesajului
attachmentsarrayFișiere, imagini, audio
reply_toUUID v7ID-ul mesajului părinte, pentru firele de discuție
actionsarrayButoane/tastaturi interactive
platform_databytesTransmitere opacă pentru funcții specifice platformei
timestampISO 8601Setat de editor

Design pe două straturi: Câmpurile comune (text, attachments, reply_to, actions) acoperă 90% din mesajele inițiate de angajați. Funcțiile specifice platformei merg în platform_data — pluginul tău le convertește în și din formatul nativ al platformei.

Fluxuri de conversație

Mesajele de canal sunt direcționate prin fluxuri de conversație separate pentru fiecare canal, pentru izolare:

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

Exemplu 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
        }
    ]
}

Mai multe capabilități

Aplicație comm

Declară "provides": ["comm"] și "permissions": ["comm:*"]. Aplicațiile comm permit comunicarea între angajații IA.

CâmpDescriere
fromID-ul angajatului expeditor
toID-ul angajatului destinatar
topicSubiectul/canalul mesajului
type"message", "mention", "proposal", "command", "info", "task"
contentCorpul mesajului

Comportamente cheie:

  • Register anunță acest angajat IA în rețea, împreună cu capabilitățile lui
  • Subscribe/Unsubscribe gestionează abonările la subiecte
  • Receive transmite în flux mesajele primite (streaming de la server, la fel ca la canale)
  • Doar o singură aplicație comm poate fi activă la un moment dat

Aplicație gateway

O aplicație gateway direcționează cererile LLM către modele. Declară "provides": ["gateway"] și "permissions": ["network:outbound", "user:token"].

GatewayRequest conține mesaje, instrumente, promptul de sistem, numărul maxim de tokeni, temperatura și un UserContext (tokenul JWT, dacă permisiunea user:token e acordată).

Tipuri GatewayEvent:

TipConținutDescriere
"text"Fragment de textToken de text transmis în flux
"tool_call"JSONModelul vrea să apeleze un instrument
"thinking"Fragment de textGândire/raționament extins
"error"Mesaj de eroareCeva n-a mers bine
"done"GolFluxul s-a încheiat

Aplicație UI

O aplicație UI oferă o interfață de configurare personalizată care se deschide în fereastra de browser integrată a lui Nebo. Declară "provides": ["ui"]. Spre deosebire de formularul de setări automat (pe care Nebo îl randează din manifestul settings), o aplicație UI servește propriul frontend complet HTML/CSS/JS.

Aplicația ta vine cu un director ui/ care conține resurse web statice (HTML, CSS, JS — de obicei un SPA cu index.html). Nebo servește aceste fișiere direct și transmite prin proxy apelurile API către aplicația ta, prin gRPC.

CaleMecanismScop
GET /api/v1/apps/{id}/ui/*Server de fișiere staticeServește fișiere din directorul tău ui/ (cu revenire SPA la index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCTransmite prin proxy cererile HTTP către UIService.HandleRequest() din aplicația ta

SDK-ul încapsulează un net/http.ServeMux standard, așa că scrii handlere HTTP Go obișnuite — SDK-ul se ocupă automat de puntea gRPC.

Exemplu Go — Interfață de tablou 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())
}

Fișierul tău ui/index.html ar face apeluri fetch către /api/v1/apps/com.example.dashboard/api/status, care sunt transmise prin proxy către handlerul tău mux.

Aplicație de programare

O aplicație de programare înlocuiește planificatorul cron integrat al lui Nebo. Declară "provides": ["schedule"] și "permissions": ["schedule:create"].

Când aplicația ta de programare pornește, Nebo direcționează toată programarea prin aplicația ta în locul motorului cron implicit. Dacă aplicația ta se blochează, Nebo revine automat la motorul integrat.

  • Aplicația ta deține starea programărilor — Nebo nu stochează programările în propria bază de date cât timp o aplicație de programare e activă
  • CRUD standard: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers este un RPC cu streaming de la server — aplicația ta trimite un mesaj de declanșare de fiecare dată când se activează o programare
  • Doar o singură aplicație de programare poate fi activă la un moment dat

Aplicații cu mai multe capabilități

O aplicație poate oferi mai multe capabilități. De exemplu, o aplicație de tablou de bord cu un instrument și o interfață 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())

Împachetare

Formatul .napp

Pentru distribuire prin NeboAI, împachetează-ți aplicația ca fișier .napp (o arhivă tar.gz):

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

Fișiere obligatorii:

FișierDimensiune maximăDescriere
manifest.json1 MBMetadatele aplicației
binary sau app500 MBExecutabil
signatures.json1 MBSemnături Ed25519
TOOL.md1 MBInstrucțiuni de folosire a instrumentului pentru angajatul IA

Reguli de securitate la extragere:

  • Fără traversarea căilor (../ e respins)
  • Fără linkuri simbolice (respinse)
  • Fără căi absolute (respinse)
  • Sunt acceptate doar numele de fișiere din lista permisă

Semnături

NeboAI semnează aplicațiile cu Ed25519. Formatul 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>"
}

În modul de dezvoltare (fără URL NeboAI configurat), verificarea semnăturii este omisă complet. Nu ai nevoie de signatures.json pentru dezvoltarea locală.

Publicare

După ce aplicația ta funcționează local, public-o prin NeboAI ca s-o distribui tuturor utilizatorilor Nebo.

Configurarea contului de dezvoltator

  1. Înregistrează un cont NeboAI la POST /api/v1/owners/register
  2. Autentifică-te ca să obții un token JWT: POST /api/v1/owners/login
  3. Creează un cont de dezvoltator: POST /api/v1/developer/accounts

Fluxul de trimitere

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

Pasul 1: Creează aplicația

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

Pasul 2: Încarcă binarele pentru platforme

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"

Încarcă câte un binar pentru fiecare platformă: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Pasul 3: Trimite la verificare

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

Procesul de verificare

  1. Scanare automată — binarele sunt scanate prin VirusTotal
  2. Verificare de către administrator — echipa NeboAI verifică metadatele, manifestul și rezultatele scanării
  3. La aprobare — NeboAI semnează aplicația cu Ed25519 și o publică
  4. La respingere — primești un motiv și poți corecta și retrimite

Timp-țintă de verificare: <24 de ore.

Publicarea actualizărilor

  1. Actualizează versiunea aplicației: PUT /api/v1/developer/apps/{id} cu noua versiune
  2. Încarcă binare noi pentru fiecare platformă
  3. Trimite din nou la verificare

Fiecare actualizare trece prin același proces de verificare. Versiunile anterioare rămân disponibile până când noua versiune e aprobată.

Metadate pentru magazin

CâmpDescriere
categoryde ex., productivity, communication, developer-tools
iconURL-ul pictogramei aplicației
visibilitypublic sau private
descriptionPoate fi mai lungă/mai bogată decât descrierea din manifest

Fluxul de dezvoltare

Dezvoltare locală

Pentru dezvoltarea locală nu e nevoie de împachetare:

  1. Creează directorul aplicației:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Scrie-ți manifest.json și codul
  3. Compilează fișierul binar:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo detectează automat noul director (sau repornește Nebo)
  5. După modificări de cod, reconstruiește binarul — monitorul de fișiere va reporni aplicația

Vizualizarea jurnalelor

Ieșirile stdout/stderr ale aplicației sunt capturate în fișiere de jurnal separate pentru fiecare aplicație:

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

Date persistente

Folosește directorul data/ (disponibil și ca variabila de mediu NEBO_APP_DATA) pentru orice fișiere pe care aplicația ta trebuie să le păstreze. Acest director rezistă la actualizările aplicației și la carantină.

Sfaturi de depanare

  • Dacă aplicația nu pornește, caută erori în logs/stderr.log
  • Asigură-te că binarul este executabil (chmod +x binary)
  • Asigură-te că asculți pe calea socketului Unix din NEBO_APP_SOCK
  • Socketul trebuie să fie gata în cel mult 10 secunde de la lansare
  • Folosește NEBO_APP_DATA pentru stocare, nu căi scrise direct în cod
  • Scrie în stderr pentru jurnalele de depanare (capturate în logs/stderr.log)

Verificare

# 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

Dezinstalare

nebo apps uninstall com.example.myapp

Abilități

Ce sunt abilitățile

Abilitățile sunt seturi de instrucțiuni care modelează felul în care se comportă Nebo într-o conversație. Când o abilitate e activă, conținutul ei e injectat direct în promptul de sistem — ghidând tonul angajatului IA, metodologia, expertiza în domeniu și folosirea instrumentelor pentru acea sesiune.

Abilitățile nu sunt cod. Sunt documente markdown cu metadate YAML. Fără compilare, fără binar, fără gRPC. O abilitate este un fișier SKILL.md într-un director. Atât.

Abilitățile sunt contextuale și temporare. Se activează când sunt relevante (prin potrivirea declanșatoarelor sau prin încărcare manuală), rămân active câteva ture și expiră când nu mai sunt necesare. Astfel contextul angajatului IA rămâne suplu — în prompt e doar îndrumarea care contează acum.

Abilitățile completează aplicațiile. Aplicațiile oferă capabilități executabile (instrumente, canale, gateway-uri). Abilitățile oferă îndrumare pentru orchestrare — cum să folosești eficient acele instrumente. O aplicație de calendar îi dă lui Nebo posibilitatea să citească și să scrie evenimente. O abilitate de „pregătire a întâlnirilor” îi spune lui Nebo cum să se pregătească pentru întâlniri folosind împreună aplicația de calendar, e-mailul și căutarea pe web.

Abilități vs. aplicații

AbilitățiAplicații
FormatMarkdown (SKILL.md)Binar compilat (.napp)
ExecuțieInjectate în promptul de sistemProces în sandbox, prin gRPC
OferăÎndrumare comportamentală, metodologieInstrumente, canale, panouri UI
Durată de viațăLimitată la sesiune, cu expirare pe bază de TTLRulează mereu
CreareScrii un fișier markdownScrii, compilezi, semnezi, împachetezi
SecuritateNu sunt necesare permisiuniSandbox cu refuz implicit

Început rapid

Creează un director în folderul de abilități Nebo, cu un fișier SKILL.md:

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

Scrie 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 monitorizează directorul de abilități cu fsnotify. Abilitatea ta e disponibilă imediat — nu e nevoie de repornire. Spune ceva ce se potrivește cu un declanșator și se activează automat.

Sau cere-i direct lui Nebo: „Creează o abilitate pentru scrierea articolelor de blog” — Nebo va scrie fișierul SKILL.md pentru tine.

Formatul SKILL.md

Fiecare abilitate este un singur fișier SKILL.md cu două părți: un frontmatter YAML între marcajele --- și un corp markdown (instrucțiunile propriu-zise injectate în promptul de sistem).

CâmpObligatoriuImplicitDescriere
nameDa—Identificator unic (devine slugul)
descriptionDa—Descriere pe un rând, afișată în catalogul de abilități
versionNu"1.0.0"Semver pentru urmărirea actualizărilor
authorNu—Autorul abilității
priorityNu0Mai mare = potrivită prima (100+ pentru suprascrieri critice)
max_turnsNu4Ture de inactivitate înainte de expirarea automată
triggersNu[]Expresii care activează automat această abilitate (potrivire de subșir, fără diferență între majuscule și minuscule)
toolsNu[]Instrumentele pe care abilitatea se așteaptă să le folosească (informativ)
dependenciesNu[]Alte abilități care trebuie să fie instalate
tagsNu[]Pentru categorisire și descoperire
platformNu[]Platforme acceptate: macos, linux, windows (gol = toate)

Cum se activează abilitățile

Abilitățile urmează un model de activare în două faze: sugestie, apoi invocare.

Faza 1: Potrivirea declanșatoarelor — De fiecare dată când un utilizator trimite un mesaj, Nebo verifică toate abilitățile înregistrate pentru potriviri cu declanșatoarele. Abilitățile potrivite apar ca sugestii în promptul de sistem. Angajatul IA vede sugestia și decide dacă invocă abilitatea.

Faza 2: Invocarea — Angajatul IA invocă o abilitate apelând:

skill(name: "code-review")

Aceasta returnează întregul șablon SKILL.md ca rezultat al instrumentului, înregistrează invocarea și reinjectează șablonul în promptul de sistem la turele următoare.

TTL și expirare:

  • Abilități potrivite automat: 4 ture de inactivitate (configurabil prin max_turns)
  • Abilități încărcate manual: 6 ture de inactivitate
  • Reinvocarea resetează cronometrul
  • Limită fixă: maximum 4 abilități active pe sesiune
  • Buget de tokeni: conținutul combinat al abilităților active e limitat la 16.000 de caractere

Gestionarea abilităților

Angajatul IA poate gestiona abilitățile prin instrumentul skill:

AcțiuneDescriereExemplu
catalogListează toate abilitățile disponibileskill(action: "catalog")
loadActivează pentru această sesiuneskill(name: "code-review", action: "load")
unloadDezactivează o abilitateskill(name: "code-review", action: "unload")
createCreează o abilitate nouă pe discskill(action: "create", content: "...")
updateActualizează o abilitate existentăskill(name: "my-skill", action: "update", content: "...")
deleteȘterge o abilitate de pe discskill(name: "my-skill", action: "delete")

Cum scrii abilități bune

Un șablon de abilitate bun are:

  1. Un titlu clar — îi spune angajatului IA în ce mod se află
  2. Principii de bază — regulile de comportament nenegociabile
  3. Metodologie — abordarea pas cu pas pentru scenariile obișnuite
  4. Exemple — tipare concrete de la mesajul utilizatorului la răspuns
  5. Antitipare — ce să NU faci (modelele învață bine din exemple negative)

Sfat: Fiecare abilitate ar trebui să facă bine un singur lucru. Nu crea o abilitate de „programare generală” — creează code-review, debugging, api-design ca abilități separate. Angajatul IA poate avea mai multe active simultan.

Abilități incluse

Nebo vine cu abilități incluse care acoperă cazurile de utilizare obișnuite:

AbilitatePrioritateDescriere
onboarding100Salutul pentru utilizatorii noi și colectarea profilului
best-friend50Abilitate de personalitate — relaxat, loial, vorbește pe față
debugging25Metodologie sistematică de depanare
api-design15Bune practici pentru designul API-urilor RESTful
code-review10Revizuire de cod structurată, cu niveluri de gravitate
database-expert10Designul bazelor de date, interogări, optimizare
git-workflow10Ramificări Git, commituri, fluxuri de lucru pentru PR-uri
security-audit10Analiză de securitate și detectarea vulnerabilităților

Acestea servesc atât ca valori implicite utile, cât și ca implementări de referință pentru crearea propriilor abilități.

Referință

Fișiere proto

Fișierele proto se află în proto/apps/v0/. SDK-urile vin cu cod pregenerat, așa că nu ai nevoie de protoc pentru dezvoltarea obișnuită.

FișierServiciuRPC-uri cheie
v0/common.proto(doar mesaje)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

Fiecare serviciu include RPC-urile HealthCheck și Configure. SDK-ul le gestionează automat pe amândouă.

Tipuri proto pentru canale

Tip de mesajDescriere
ChannelSendRequestPlicul mesajului trimis, cu message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID-ul mesajului pe platformă, pentru firele de discuție
InboundMessagePlicul mesajului primit, cu toate câmpurile comune + timestamp
MessageSenderIdentitatea botului (name, role, botId) — completată de broker
AttachmentAtașament de tip fișier/imagine/audio (type, url, filename, size)
MessageActionAcțiune interactivă de buton/tastatură (label, callback_id)

Identitatea și rolurile boților

Boții Nebo au un model de identitate pe trei axe:

  • creature — Ce este botul (arhetip): „Strateg cu minte ageră”, „Cercetător meticulos”
  • role — Ce relație are cu utilizatorul: „Prieten”, „COO”, „Mentor”
  • vibe — Energia lui (stilul de comunicare): „Relaxat, dar cu opinii”, „Cald și încurajator”

Când pluginul tău de canal primește un mesaj de trimis, câmpul sender conține name și role ale botului. Folosește-le ca să formatezi numele afișat pentru platforma ta. Rolul nu e un titlu de post — descrie o relație. „Prieten”, „Fiu” și „Mentor” sunt roluri valide, alături de „COO” și „DevLead”.