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.
| Stare | Limbaje |
|---|---|
| Acceptate | Go (recomandat), Rust, C/C++, Zig |
| Respinse | Python, 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ă
- Creează
manifest.jsoncuid,name,version,provides - Scrie
TOOL.md, care descrie cum ar trebui să-ți folosească angajatul IA instrumentul - Instalează SDK-ul (
go get github.com/neboloop/nebo-sdk-go) - Implementează interfața de handler pentru capabilitatea ta (
ToolHandler,ChannelHandleretc.) - Înregistrează handlerul și apelează
app.Run() - Construiește un binar nativ (
go build -o binary .) - Pune binarul + manifest.json + TOOL.md în directorul
apps/<your-app-id>/ - 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âmp | Descriere |
|---|---|
id | Identificator în format de domeniu inversat (de ex., com.mycompany.myapp) |
name | Nume lizibil pentru oameni |
version | Șir Semver |
provides | Cel puțin o capabilitate (vezi mai jos) |
Câmpuri opționale:
| Câmp | Implicit | Descriere |
|---|---|---|
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:
| Capabilitate | Serviciu gRPC | Descriere |
|---|---|---|
gateway | GatewayService | Rutarea modelelor LLM |
tool:<name> | ToolService | Un instrument cu nume pentru angajatul IA |
channel:<name> | ChannelService | Un canal de mesagerie |
comm | CommService | Comunicare între angajații IA |
ui | UIService | Interfață personalizată cu proxy HTTP |
schedule | ScheduleService | Programare personalizată |
vision | ToolService | Procesare vizuală |
browser | ToolService | Automatizarea 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.
| Prefix | Exemple | Descriere |
|---|---|---|
network: | network:outbound, network:* | Acces la rețea |
filesystem: | filesystem:read, filesystem:write | Acces la sistemul de fișiere |
memory: | memory:read, memory:write | Acces la memoria angajatului IA |
session: | session:read | Sesiuni de conversație |
tool: | tool:shell, tool:file | Folosirea altor instrumente |
shell: | shell:exec | Executarea comenzilor shell |
channel: | channel:send, channel:* | Operațiuni pe canale |
comm: | comm:send, comm:* | Comunicare între angajații IA |
model: | model:chat | Acces la modele IA |
user: | user:token | Primirea JWT-ului utilizatorului în cereri |
schedule: | schedule:create | Gestionarea joburilor cron |
database: | database:query | Acces la baza de date |
storage: | storage:read, storage:write | Stocare persistentă |
context: | context:read | Acces la contextul angajatului IA |
subagent: | subagent:spawn | Operațiuni cu subagenți |
lane: | lane:enqueue | Operațiuni pe benzi |
notification: | notification:send | Notificări push |
embedding: | embedding:search | Acces la embeddinguri vectoriale |
skill: | skill:invoke | Invocarea abilităților |
advisor: | advisor:consult | Acces la sistemul de consilieri |
mcp: | mcp:connect | Acces la serverele MCP |
voice: | voice:record | Acces la voce/audio |
browser: | browser:navigate | Automatizarea browserului |
oauth: | oauth:google, oauth:* | Acces la tokenurile OAuth |
settings: | settings:read | Acces 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”.
| Tip | Descriere |
|---|---|
text | Câmp de text pe un singur rând |
password | Câmp de text mascat |
toggle | Comutator boolean pornit/oprit |
select | Listă derulantă cu opțiuni predefinite |
number | Câmp numeric |
url | Câ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âmp | Descriere |
|---|---|
provider | Furnizor OAuth: "google", "microsoft", "github" |
scopes | Tablou 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_DIR | Directorul de instalare al aplicației |
NEBO_APP_SOCK | Calea către socketul Unix care trebuie creat |
NEBO_APP_ID | ID-ul aplicației din manifest |
NEBO_APP_NAME | Numele aplicației din manifest |
NEBO_APP_VERSION | Versiunea aplicației din manifest |
NEBO_APP_DATA | Calea către directorul data/ al aplicației |
PATH | PATH-ul sistemului (transmis mai departe) |
HOME | Directorul home al utilizatorului (transmis mai departe) |
TMPDIR | Directorul 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
- Nebo citește
manifest.jsonși îl validează - Găsește executabilul
binarysauappîn directorul aplicației - Verifică existența marcajului
.quarantined(refuză să lanseze aplicațiile aflate în carantină) - Verificarea revocării (doar pentru aplicațiile distribuite de NeboAI)
- Verificarea semnăturii (doar pentru aplicațiile distribuite de NeboAI, omisă în modul de dezvoltare)
- Validarea binarului (respinge linkurile simbolice, scripturile, fișierele neexecutabile și fișierele prea mari)
- Curăță socketul rămas de la rularea anterioară
- Creează directorul
data/pentru stocarea în sandbox - Configurează fișiere de jurnal pentru fiecare aplicație (
logs/stdout.log,logs/stderr.log) - Pornește binarul cu un mediu igienizat și cu izolarea grupului de procese
- Așteaptă să apară socketul Unix (backoff exponențial, maximum 10 secunde)
- Se conectează prin gRPC peste socketul Unix
- Creează clienți gRPC specifici capabilităților, pe baza
provides - Rulează verificarea stării de sănătate
- Î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ă:
- Include întotdeauna un câmp
actionca enum de tip șir, obligatoriu - Adaugă un câmp
resource(enum de tip șir, obligatoriu) doar dacă instrumentul tău gestionează mai multe tipuri distincte de resurse - Toate celelalte câmpuri sunt parametri specifici acțiunii
- Descrierea enumului
actionar 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ă
- Nebo apelează
ID()ca să obțină identificatorul unic al canalului tău - Nebo apelează
Connect()cu configurația din setările aplicației tale - Nebo deschide un flux
Receive()— aplicația ta trimite mesajele primite ori de câte ori un utilizator îi scrie botului - Mesajele primite sunt direcționate către banda principală de conversație a angajatului IA
- Când angajatul IA vrea să trimită un mesaj, Nebo apelează
Send()cu plicul de mesaj v1 - 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âmp | Tip | Descriere |
|---|---|---|
message_id | UUID v7 | ID unic ordonat în timp |
channel_id | {type}:{platform_id} | Identificator de canal care poate fi rutat |
sender | object | Identitatea botului — nume, rol, botId |
text | string | Corpul mesajului |
attachments | array | Fișiere, imagini, audio |
reply_to | UUID v7 | ID-ul mesajului părinte, pentru firele de discuție |
actions | array | Butoane/tastaturi interactive |
platform_data | bytes | Transmitere opacă pentru funcții specifice platformei |
timestamp | ISO 8601 | Setat 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âmp | Descriere |
|---|---|
from | ID-ul angajatului expeditor |
to | ID-ul angajatului destinatar |
topic | Subiectul/canalul mesajului |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Corpul mesajului |
Comportamente cheie:
Registeranunță acest angajat IA în rețea, împreună cu capabilitățile luiSubscribe/Unsubscribegestionează abonările la subiecteReceivetransmite î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:
| Tip | Conținut | Descriere |
|---|---|---|
"text" | Fragment de text | Token de text transmis în flux |
"tool_call" | JSON | Modelul vrea să apeleze un instrument |
"thinking" | Fragment de text | Gândire/raționament extins |
"error" | Mesaj de eroare | Ceva n-a mers bine |
"done" | Gol | Fluxul 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.
| Cale | Mecanism | Scop |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Server de fișiere statice | Servește fișiere din directorul tău ui/ (cu revenire SPA la index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Transmite 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 Triggerseste 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șier | Dimensiune maximă | Descriere |
|---|---|---|
manifest.json | 1 MB | Metadatele aplicației |
binary sau app | 500 MB | Executabil |
signatures.json | 1 MB | Semnături Ed25519 |
TOOL.md | 1 MB | Instrucț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
- Înregistrează un cont NeboAI la
POST /api/v1/owners/register - Autentifică-te ca să obții un token JWT:
POST /api/v1/owners/login - 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
- Scanare automată — binarele sunt scanate prin VirusTotal
- Verificare de către administrator — echipa NeboAI verifică metadatele, manifestul și rezultatele scanării
- La aprobare — NeboAI semnează aplicația cu Ed25519 și o publică
- La respingere — primești un motiv și poți corecta și retrimite
Timp-țintă de verificare: <24 de ore.
Publicarea actualizărilor
- Actualizează versiunea aplicației:
PUT /api/v1/developer/apps/{id}cu noua versiune - Încarcă binare noi pentru fiecare platformă
- 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âmp | Descriere |
|---|---|
category | de ex., productivity, communication, developer-tools |
icon | URL-ul pictogramei aplicației |
visibility | public sau private |
description | Poate fi mai lungă/mai bogată decât descrierea din manifest |
Fluxul de dezvoltare
Dezvoltare locală
Pentru dezvoltarea locală nu e nevoie de împachetare:
- Creează directorul aplicației:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Scrie-ți
manifest.jsonși codul - Compilează fișierul binar:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo detectează automat noul director (sau repornește Nebo)
- 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_DATApentru 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ăți | Aplicații | |
|---|---|---|
| Format | Markdown (SKILL.md) | Binar compilat (.napp) |
| Execuție | Injectate în promptul de sistem | Proces în sandbox, prin gRPC |
| Oferă | Îndrumare comportamentală, metodologie | Instrumente, canale, panouri UI |
| Durată de viață | Limitată la sesiune, cu expirare pe bază de TTL | Rulează mereu |
| Creare | Scrii un fișier markdown | Scrii, compilezi, semnezi, împachetezi |
| Securitate | Nu sunt necesare permisiuni | Sandbox 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âmp | Obligatoriu | Implicit | Descriere |
|---|---|---|---|
name | Da | — | Identificator unic (devine slugul) |
description | Da | — | Descriere pe un rând, afișată în catalogul de abilități |
version | Nu | "1.0.0" | Semver pentru urmărirea actualizărilor |
author | Nu | — | Autorul abilității |
priority | Nu | 0 | Mai mare = potrivită prima (100+ pentru suprascrieri critice) |
max_turns | Nu | 4 | Ture de inactivitate înainte de expirarea automată |
triggers | Nu | [] | Expresii care activează automat această abilitate (potrivire de subșir, fără diferență între majuscule și minuscule) |
tools | Nu | [] | Instrumentele pe care abilitatea se așteaptă să le folosească (informativ) |
dependencies | Nu | [] | Alte abilități care trebuie să fie instalate |
tags | Nu | [] | Pentru categorisire și descoperire |
platform | Nu | [] | 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țiune | Descriere | Exemplu |
|---|---|---|
catalog | Listează toate abilitățile disponibile | skill(action: "catalog") |
load | Activează pentru această sesiune | skill(name: "code-review", action: "load") |
unload | Dezactivează o abilitate | skill(name: "code-review", action: "unload") |
create | Creează o abilitate nouă pe disc | skill(action: "create", content: "...") |
update | Actualizează o abilitate existentă | skill(name: "my-skill", action: "update", content: "...") |
delete | Șterge o abilitate de pe disc | skill(name: "my-skill", action: "delete") |
Cum scrii abilități bune
Un șablon de abilitate bun are:
- Un titlu clar — îi spune angajatului IA în ce mod se află
- Principii de bază — regulile de comportament nenegociabile
- Metodologie — abordarea pas cu pas pentru scenariile obișnuite
- Exemple — tipare concrete de la mesajul utilizatorului la răspuns
- 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:
| Abilitate | Prioritate | Descriere |
|---|---|---|
onboarding | 100 | Salutul pentru utilizatorii noi și colectarea profilului |
best-friend | 50 | Abilitate de personalitate — relaxat, loial, vorbește pe față |
debugging | 25 | Metodologie sistematică de depanare |
api-design | 15 | Bune practici pentru designul API-urilor RESTful |
code-review | 10 | Revizuire de cod structurată, cu niveluri de gravitate |
database-expert | 10 | Designul bazelor de date, interogări, optimizare |
git-workflow | 10 | Ramificări Git, commituri, fluxuri de lucru pentru PR-uri |
security-audit | 10 | Analiză 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șier | Serviciu | RPC-uri cheie |
|---|---|---|
v0/common.proto | (doar mesaje) | 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 |
Fiecare serviciu include RPC-urile HealthCheck și Configure. SDK-ul le gestionează automat pe amândouă.
Tipuri proto pentru canale
| Tip de mesaj | Descriere |
|---|---|
ChannelSendRequest | Plicul mesajului trimis, cu message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID-ul mesajului pe platformă, pentru firele de discuție |
InboundMessage | Plicul mesajului primit, cu toate câmpurile comune + timestamp |
MessageSender | Identitatea botului (name, role, botId) — completată de broker |
Attachment | Atașament de tip fișier/imagine/audio (type, url, filename, size) |
MessageAction | Acț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”.