NeboAI
NeboAI
Aan de slag

Bouw apps voor Nebo

Geef je AI nieuwe superkrachten. Tools, kanalen, gateways, UI-panelen — alles wat je kunt bedenken, gecompileerd tot een native binary.

Overzicht

Wat Nebo is

Nebo is een persoonlijke AI-assistent voor de desktop — een AI-medewerker die altijd draait en je digitale leven beheert. Zie Nebo zoals je een smartphone ziet: een krachtig platform dat pas echt het verschil maakt door zijn apps.

Op zichzelf is Nebo al een capabele AI-medewerker met geheugen, planning, surfen op het web, bestandsbeheer en shell-toegang. Maar de echte doorbraak zit in de apps. Zoals de kracht van een smartphone uit zijn app-ecosysteem komt, zo komt de kracht van Nebo uit de apps die uitbreiden wat hij kan.

Wat apps zijn

Nebo-apps zijn op zichzelf staande, vooraf gecompileerde eenheden met ongelooflijke functionaliteit. Elke app geeft Nebo een nieuwe superkracht — agendabeheer, e-mail sorteren, projecten bijhouden, domotica, financiële analyse — alles wat een ontwikkelaar maar kan bedenken.

Apps bieden ongelooflijk veel kracht op een zeer veilige manier. Elke app draait in een sandbox met machtigingen die standaard geweigerd zijn. Hij heeft alleen toegang tot wat zijn manifest declareert en de gebruiker goedkeurt.

De interface is 100% conversationeel. Gebruikers werken niet met apps via aparte schermen of dashboards. Ze praten met Nebo, en Nebo gebruikt de tools van de app om dingen gedaan te krijgen. "Wat staat er morgen in mijn agenda?" — Nebo roept de agenda-app aan. "Plan een afspraak met Sarah om 15.00 uur" — Nebo roept de agenda-app aan. De gebruiker verlaat het gesprek nooit.

Apps kunnen optioneel een instellingen-UI bieden — een configuratiepaneel dat opent in het ingebouwde browservenster van Nebo. Hier voeren gebruikers API-sleutels in, zetten ze functies aan of uit en configureren ze de app. De instellingen-UI wordt aangestuurd door de settings-array in het manifest (Nebo rendert het formulier automatisch), of de app kan via de ui-capability een eigen, volledig aangepaste UI leveren.

Apps vervangen en breiden de ingebouwde mogelijkheden van Nebo uit. Nebo wordt geleverd met basistools van het platform (lokale agendatoegang, schermafbeeldingen, enz.). Als je een agenda-app installeert, vervangt die de ingebouwde agendatool en wordt hij een superset — lokaal + cloud + samenvoegen + beschikbaarheid controleren.

Beleid voor uitsluitend gecompileerde code

Nebo hanteert een strikt beleid dat alleen gecompileerde binaries toestaat. Alle apps moeten native gecompileerde uitvoerbare bestanden zijn.

StatusTalen
OndersteundGo (aanbevolen), Rust, C/C++, Zig
GeweigerdPython, Node.js, Ruby, Java, .NET, shell-scripts

Onderbouwing:

  • Voorkomen dat AI zichzelf aanpast — Een AI-medewerker met shell-toegang zou het gedrag van een geïnterpreteerd script tijdens runtime kunnen wijzigen. Gecompileerde binaries zijn na ondertekening onveranderlijk.
  • Integriteit van handtekeningen — Ed25519-handtekeningen dekken de ruwe bytes van de binary. Een ondertekende binary kan niet worden gewijzigd zonder dat de handtekening ongeldig wordt.
  • Handhaving van de sandbox — Validatie van het binaire formaat (ELF/Mach-O/PE magic bytes) is een snelle, betrouwbare poort.

Snel aan de slag

De SDK installeren

Officiële SDK's regelen de volledige gRPC-serverconfiguratie, signaalafhandeling en protocolkoppeling. Jij implementeert alleen handler-interfaces.

Go (aanbevolen):

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

Rust (binnenkort beschikbaar):

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

C/C++ (binnenkort beschikbaar):

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

Mapstructuur van een app

Apps staan in de submap apps/ van je Nebo-datamap:

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

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

Checklist voor een minimale app

  1. Maak manifest.json aan met id, name, version, provides
  2. Schrijf TOOL.md waarin staat hoe de AI-medewerker je tool moet gebruiken
  3. Installeer de SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Implementeer de handler-interface voor je capability (ToolHandler, ChannelHandler, enz.)
  5. Registreer de handler en roep app.Run() aan
  6. Bouw een native binary (go build -o binary .)
  7. Zet binary + manifest.json + TOOL.md in de map apps/<your-app-id>/
  8. Nebo vindt hem automatisch en start hem

Configuratie

manifest.json

Elke app heeft een manifest.json nodig:

{
    "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
        }
    ]
}

Verplichte velden:

VeldBeschrijving
idIdentificatie in omgekeerde-domeinnotatie (bijv. com.mycompany.myapp)
nameLeesbare naam
versionSemver-tekenreeks
providesMinstens één capability (zie hieronder)

Optionele velden:

VeldStandaardBeschrijving
runtime"local""local" of "remote"
protocol"grpc"Alleen "grpc" wordt ondersteund
permissions[]Waartoe de app toegang nodig heeft
description""Wordt getoond in de UI
settings[]Configureerbare instellingen (weergegeven in de instellingen-UI)
oauth[]Vereisten voor OAuth-providers (zie het OAuth-gedeelte hieronder)

Capabilities

Declareer wat je app levert:

CapabilitygRPC-serviceBeschrijving
gatewayGatewayServiceRoutering van LLM-modellen
tool:<name>ToolServiceEen tool met een naam voor de AI-medewerker
channel:<name>ChannelServiceEen berichtenkanaal
commCommServiceCommunicatie tussen AI-medewerkers
uiUIServiceAangepaste UI met HTTP-proxy
scheduleScheduleServiceAangepaste planning
visionToolServiceBeeldverwerking
browserToolServiceBrowserautomatisering

Een app kan meerdere capabilities leveren. Een app kan bijvoorbeeld zowel een tool als een UI-paneel leveren.

Machtigingen

Machtigingen bepalen waartoe de app toegang heeft. Standaard geweigerd — wat niet is gedeclareerd, kan de app niet gebruiken.

VoorvoegselVoorbeeldenBeschrijving
network:network:outbound, network:*Netwerktoegang
filesystem:filesystem:read, filesystem:writeToegang tot het bestandssysteem
memory:memory:read, memory:writeToegang tot het geheugen van de AI-medewerker
session:session:readGesprekssessies
tool:tool:shell, tool:fileAndere tools gebruiken
shell:shell:execShell-opdrachten uitvoeren
channel:channel:send, channel:*Kanaalbewerkingen
comm:comm:send, comm:*Communicatie tussen AI-medewerkers
model:model:chatToegang tot AI-modellen
user:user:tokenJWT van de gebruiker ontvangen in verzoeken
schedule:schedule:createBeheer van cronjobs
database:database:queryToegang tot de database
storage:storage:read, storage:writePermanente opslag
context:context:readToegang tot de context van de AI-medewerker
subagent:subagent:spawnBewerkingen met sub-agents
lane:lane:enqueueLane-bewerkingen
notification:notification:sendPushmeldingen
embedding:embedding:searchToegang tot vector-embeddings
skill:skill:invokeSkills aanroepen
advisor:advisor:consultToegang tot het adviseurssysteem
mcp:mcp:connectToegang tot MCP-servers
voice:voice:recordToegang tot spraak/audio
browser:browser:navigateBrowserautomatisering
oauth:oauth:google, oauth:*Toegang tot OAuth-tokens
settings:settings:readToegang tot instellingen
capability:capability:registerRegistratie van capabilities

Jokertekens in machtigingen worden ondersteund: network:* komt overeen met elke controle op een network:-machtiging.

Instellingen

Instellingen verschijnen in de Nebo-UI in het instellingenpaneel van de app. Nebo slaat ze op in de database en stuurt ze via de Configure-RPC naar je app wanneer ze veranderen.

Je instellingenschema wordt opgenomen in de vermelding van je app in de NeboAI-appstore. Apps met verplichte instellingen die nog niet zijn ingevuld, krijgen in de UI het label "Instellen vereist".

TypeBeschrijving
textTekstinvoer op één regel
passwordGemaskeerde tekstinvoer
toggleBooleaanse aan/uit-schakelaar
selectVervolgkeuzelijst met vooraf ingestelde opties
numberNumerieke invoer
urlURL-invoer met validatie
{
    "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"}
    ]
}

OAuth-vereisten

Apps kunnen vereisten voor OAuth-providers declareren. De OAuth-broker van Nebo regelt de hele flow — apps ontvangen tokens automatisch via de Configure-RPC.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
VeldBeschrijving
providerOAuth-provider: "google", "microsoft", "github"
scopesArray met de OAuth-scopes die de app nodig heeft

Als de gebruiker de app installeert, vraagt Nebo hem om de vereiste OAuth-scopes te autoriseren. De app ontvangt vernieuwde tokens via de Configure-RPC zonder de OAuth-flow zelf af te handelen.

Omgevingsvariabelen

Het proces van je app krijgt een opgeschoonde omgeving. Alle geheimen worden verwijderd. Je krijgt:

VariabeleWaarde
NEBO_APP_DIRInstallatiemap van de app
NEBO_APP_SOCKPad naar de Unix-socket die moet worden aangemaakt
NEBO_APP_IDApp-ID uit het manifest
NEBO_APP_NAMEApp-naam uit het manifest
NEBO_APP_VERSIONApp-versie uit het manifest
NEBO_APP_DATAPad naar de map data/ van de app
PATHSysteem-PATH (doorgegeven)
HOMEThuismap van de gebruiker (doorgegeven)
TMPDIRTijdelijke map (doorgegeven)

Belangrijk: Je binary moet een gRPC-server aanmaken die luistert op de Unix-socket in NEBO_APP_SOCK. Nebo wacht maximaal 10 seconden tot deze socket verschijnt.

Opstartvolgorde van een app

  1. Nebo leest manifest.json en valideert het
  2. Zoekt het uitvoerbare bestand binary of app in de app-map
  3. Controleert op een .quarantined-markering (apps in quarantaine worden niet gestart)
  4. Controle op intrekking (alleen apps die via NeboAI worden verspreid)
  5. Verificatie van de handtekening (alleen apps die via NeboAI worden verspreid, overgeslagen in dev)
  6. Validatie van de binary (weigert symlinks, scripts, niet-uitvoerbare en te grote bestanden)
  7. Ruimt een verouderde socket van een vorige run op
  8. Maakt de map data/ aan voor opslag in de sandbox
  9. Zet logbestanden per app op (logs/stdout.log, logs/stderr.log)
  10. Start de binary met een opgeschoonde omgeving en isolatie per procesgroep
  11. Wacht tot de Unix-socket verschijnt (exponentiële backoff, maximaal 10 seconden)
  12. Maakt verbinding via gRPC over de Unix-socket
  13. Maakt gRPC-clients per capability aan op basis van provides
  14. Voert een gezondheidscontrole uit
  15. Registreert capabilities bij de AI-medewerker (tools, gateway, comm, enz.)

Tool-apps

Declareer "provides": ["tool:my_tool_name"] in je manifest.

Het STRAP-patroon

Alle tool-apps van Nebo moeten voor hun schema en uitvoeringsroutering het STRAP (Single Tool Resource Action Pattern) gebruiken. Dit is hetzelfde patroon dat Nebo intern gebruikt om meer dan 35 losse tools samen te voegen tot 4 domeintools — wat de LLM-contextoverhead met ~80% verlaagt.

Kernidee: In plaats van meerdere tools te registreren (get_events, check_availability, suggest_slots), registreer je ÉÉN tool met de velden action (en optioneel resource) die naar de juiste handler routeren.

Voorbeeld met één resource (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")

Voorbeeld met meerdere resources (projectmanager):

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

Schemaregels:

  1. Neem altijd een action-veld op als verplichte string-enum
  2. Voeg alleen een resource-veld (verplichte string-enum) toe als je tool meerdere verschillende resourcetypes beheert
  3. Alle andere velden zijn parameters die bij een specifieke actie horen
  4. De beschrijving van de action-enum moet alle beschikbare acties opsommen

Waarom STRAP ertoe doet:

  • LLM's leren het routeringspatroon van action één keer en passen het toe op alle bewerkingen
  • Tooldefinities nemen ~6% van de context in beslag — STRAP verlaagt dat met 80%
  • Nieuwe bewerkingen zijn gewoon extra enum-waarden, geen nieuwe toolregistraties
  • Werkt precies hetzelfde bij gehoste en lokale modellen

Go-voorbeeld — Rekenmachinetool

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

Bouwen en installeren:

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/

Rust-voorbeeld

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

C-voorbeeld

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

Kanaal-apps

Declareer "provides": ["channel:my_channel"] en "permissions": ["channel:send"].

Kanaal-apps verbinden externe berichtenplatforms (Telegram, Discord, Slack, enz.) met de AI-medewerker van Nebo. Als een gebruiker een bericht stuurt op het externe platform, streamt je app het via Receive naar Nebo. Als de AI-medewerker wil antwoorden, roept Nebo de Send van je app aan.

Hoe het werkt

  1. Nebo roept ID() aan om de unieke identificatie van je kanaal op te halen
  2. Nebo roept Connect() aan met de configuratie uit de instellingen van je app
  3. Nebo opent een Receive()-stream — je app stuurt inkomende berichten door telkens als een gebruiker de bot een bericht stuurt
  4. Inkomende berichten worden naar de hoofdgesprekslane van de AI-medewerker gerouteerd
  5. Als de AI-medewerker een bericht wil versturen, roept Nebo Send() aan met de v1-berichtenvelop
  6. Bij het afsluiten roept Nebo Disconnect() aan

v1-berichtenvelop

Alle kanaalberichten — inkomend en uitgaand — gebruiken de gemeenschappelijke berichtenvelop:

{
  "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"
}
VeldTypeBeschrijving
message_idUUID v7Unieke ID, op tijd gesorteerd
channel_id{type}:{platform_id}Routeerbare kanaalidentificatie
senderobjectIdentiteit van de bot — naam, rol, botId
textstringBerichttekst
attachmentsarrayBestanden, afbeeldingen, audio
reply_toUUID v7ID van het bovenliggende bericht voor threads
actionsarrayInteractieve knoppen/toetsenborden
platform_databytesOndoorzichtige doorgifte voor platformspecifieke functies
timestampISO 8601Wordt ingesteld door de uitgever

Ontwerp in twee lagen: De gemeenschappelijke velden (text, attachments, reply_to, actions) dekken 90% van de berichten die medewerkers zelf versturen. Platformspecifieke functies gaan in platform_data — je plug-in zet ze om van en naar het eigen formaat van het platform.

Gespreksstreams

Kanaalberichten worden voor isolatie via gespreksstreams per kanaal gerouteerd:

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

Go-voorbeeld — Telegram-kanaal

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

Meer capabilities

Comm-app

Declareer "provides": ["comm"] en "permissions": ["comm:*"]. Comm-apps maken communicatie tussen AI-medewerkers mogelijk.

VeldBeschrijving
fromID van de verzendende medewerker
toID van de ontvangende medewerker
topicOnderwerp/kanaal van het bericht
type"message", "mention", "proposal", "command", "info", "task"
contentBerichttekst

Belangrijkste gedrag:

  • Register meldt deze AI-medewerker met zijn capabilities aan op het netwerk
  • Subscribe/Unsubscribe beheren abonnementen op onderwerpen
  • Receive streamt inkomende berichten (server-streaming, net als bij kanalen)
  • Er kan maar één comm-app tegelijk actief zijn

Gateway-app

Een gateway-app routeert LLM-verzoeken naar modellen. Declareer "provides": ["gateway"] en "permissions": ["network:outbound", "user:token"].

GatewayRequest bevat berichten, tools, systeemprompt, maximaal aantal tokens, temperatuur en een UserContext (JWT-token als de machtiging user:token is verleend).

Typen GatewayEvent:

TypeInhoudBeschrijving
"text"TekstfragmentStreamend teksttoken
"tool_call"JSONModel wil een tool aanroepen
"thinking"TekstfragmentUitgebreid nadenken/redeneren
"error"FoutmeldingEr is iets misgegaan
"done"LeegStream is voltooid

UI-app

Een UI-app levert een aangepaste configuratie-interface die opent in het ingebouwde browservenster van Nebo. Declareer "provides": ["ui"]. Anders dan het automatische instellingenformulier (dat Nebo rendert op basis van je settings-manifest) levert een UI-app zijn eigen volledige HTML/CSS/JS-frontend.

Je app wordt geleverd met een map ui/ vol statische webbestanden (HTML, CSS, JS — meestal een SPA met index.html). Nebo serveert deze bestanden rechtstreeks en stuurt API-aanroepen via gRPC door naar je app.

PadMechanismeDoel
GET /api/v1/apps/{id}/ui/*Statische bestandsserverServeert bestanden uit je map ui/ (SPA-fallback naar index.html)
ANY /api/v1/apps/{id}/api/*gRPC-proxyStuurt HTTP-verzoeken door naar UIService.HandleRequest() van je app

De SDK verpakt een standaard net/http.ServeMux, zodat je gewone Go-HTTP-handlers schrijft — de SDK regelt de gRPC-koppeling automatisch.

Go-voorbeeld — Dashboard-UI:

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

Je ui/index.html doet fetch-aanroepen naar /api/v1/apps/com.example.dashboard/api/status, die worden doorgestuurd naar je mux-handler.

Planning-app

Een planning-app vervangt de ingebouwde cron-planner van Nebo. Declareer "provides": ["schedule"] en "permissions": ["schedule:create"].

Zodra je planning-app start, routeert Nebo alle planning via je app in plaats van via de standaard cron-engine. Als je app crasht, valt Nebo automatisch terug op de ingebouwde engine.

  • Je app beheert de planningsstatus — Nebo slaat geen planningen op in zijn eigen database zolang er een planning-app actief is
  • Standaard CRUD: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers is een server-streaming-RPC — je app stuurt een triggerbericht telkens als een planning afgaat
  • Er kan maar één planning-app tegelijk actief zijn

Apps met meerdere capabilities

Een app kan meerdere capabilities leveren. Bijvoorbeeld een dashboard-app met zowel een tool als een 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())

Verpakken

.napp-formaat

Voor distributie via NeboAI verpak je je app als .napp-bestand (een tar.gz-archief):

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

Verplichte bestanden:

BestandMax. grootteBeschrijving
manifest.json1 MBMetadata van de app
binary of app500 MBUitvoerbaar bestand
signatures.json1 MBEd25519-handtekeningen
TOOL.md1 MBToolinstructies voor de AI-medewerker

Beveiligingsregels bij het uitpakken:

  • Geen path traversal (../ wordt geweigerd)
  • Geen symlinks (worden geweigerd)
  • Geen absolute paden (worden geweigerd)
  • Alleen toegestane bestandsnamen worden geaccepteerd

Handtekeningen

NeboAI ondertekent apps met Ed25519. Het formaat van signatures.json:

{
    "key_id": "a1b2c3d4",
    "algorithm": "ed25519",
    "manifest_signature": "<base64 signature of raw manifest.json bytes>",
    "binary_sha256": "<hex SHA256 of binary>",
    "binary_signature": "<base64 signature of raw binary bytes>"
}

In dev-modus (geen NeboAI-URL geconfigureerd) wordt de verificatie van handtekeningen helemaal overgeslagen. Voor lokale ontwikkeling heb je signatures.json niet nodig.

Publiceren

Zodra je app lokaal werkt, publiceer je hem via NeboAI om hem onder alle Nebo-gebruikers te verspreiden.

Ontwikkelaarsaccount instellen

  1. Registreer een NeboAI-account via POST /api/v1/owners/register
  2. Log in om een JWT-token te krijgen: POST /api/v1/owners/login
  3. Maak een ontwikkelaarsaccount aan: POST /api/v1/developer/accounts

Indieningsproces

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

Stap 1: Maak de app aan

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

Stap 2: Upload binaries per platform

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"

Upload één binary per platform: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Stap 3: Dien in ter beoordeling

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

Beoordelingsproces

  1. Automatische scan — binaries worden gescand via VirusTotal
  2. Beoordeling door beheerders — het NeboAI-team beoordeelt metadata, manifest en scanresultaten
  3. Bij goedkeuring — NeboAI ondertekent de app met Ed25519 en publiceert hem
  4. Bij afwijzing — je krijgt een reden en kunt het oplossen en opnieuw indienen

Beoogde beoordelingstijd: <24 uur.

Updates uitbrengen

  1. Werk de versie van de app bij: PUT /api/v1/developer/apps/{id} met de nieuwe versie
  2. Upload nieuwe binaries voor elk platform
  3. Dien opnieuw in ter beoordeling

Elke update doorloopt hetzelfde beoordelingsproces. Eerdere versies blijven beschikbaar tot de nieuwe versie is goedgekeurd.

Metadata voor de store

VeldBeschrijving
categorybijv. productivity, communication, developer-tools
iconURL van het app-pictogram
visibilitypublic of private
descriptionMag langer/uitgebreider zijn dan de beschrijving in het manifest

Ontwikkelworkflow

Lokale ontwikkeling

Voor lokale ontwikkeling hoef je niets te verpakken:

  1. Maak de map voor je app aan:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Schrijf je manifest.json en code
  3. Bouw je binary:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo detecteert de nieuwe map automatisch (of start Nebo opnieuw)
  5. Bouw na codewijzigingen de binary opnieuw — de bestandswatcher herstart de app

Logs bekijken

De stdout/stderr van een app worden vastgelegd in logbestanden per app:

tail -f ~/Library/Application\ Support/Nebo/apps/com.example.myapp/logs/stdout.log
tail -f ~/Library/Application\ Support/Nebo/apps/com.example.myapp/logs/stderr.log

Permanente data

Gebruik de map data/ (ook beschikbaar als omgevingsvariabele NEBO_APP_DATA) voor alle bestanden die je app moet bewaren. Deze map blijft bestaan bij app-updates en quarantaine.

Tips voor debuggen

  • Als je app niet start, kijk dan in logs/stderr.log naar fouten
  • Zorg dat de binary uitvoerbaar is (chmod +x binary)
  • Controleer of je luistert op het Unix-socketpad uit NEBO_APP_SOCK
  • De socket moet binnen 10 seconden na het starten klaar zijn
  • Gebruik NEBO_APP_DATA voor opslag, geen hardgecodeerde paden
  • Schrijf naar stderr voor debuglogs (vastgelegd in logs/stderr.log)

Verifiëren

# 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

Verwijderen

nebo apps uninstall com.example.myapp

Skills

Wat skills zijn

Skills zijn sets instructies die bepalen hoe Nebo zich tijdens een gesprek gedraagt. Als een skill actief is, wordt de inhoud ervan rechtstreeks in de systeemprompt gezet — en stuurt die de toon, werkwijze, vakkennis en het toolgebruik van de AI-medewerker voor die sessie.

Skills zijn geen code. Het zijn markdown-documenten met YAML-metadata. Geen compilatie, geen binary, geen gRPC. Een skill is een SKILL.md-bestand in een map. Meer is het niet.

Skills zijn contextueel en tijdelijk. Ze worden actief wanneer ze relevant zijn (via triggers of handmatig laden), blijven een paar beurten actief en verlopen wanneer ze niet meer nodig zijn. Zo blijft de context van de AI-medewerker slank — alleen de aanwijzingen die nu tellen staan in de prompt.

Skills vullen apps aan. Apps leveren uitvoerbare mogelijkheden (tools, kanalen, gateways). Skills geven aanwijzingen voor de regie — hoe je die tools goed inzet. Een agenda-app geeft Nebo de mogelijkheid om afspraken te lezen en te schrijven. Een skill "vergadering voorbereiden" vertelt Nebo hoe hij vergaderingen voorbereidt met die agenda-app, e-mail en zoeken op het web samen.

Skills versus apps

SkillsApps
FormaatMarkdown (SKILL.md)Gecompileerde binary (.napp)
RuntimeIn de systeemprompt geplaatstProces in een sandbox via gRPC
LevertAanwijzingen voor gedrag, werkwijzeTools, kanalen, UI-panelen
LevensduurPer sessie, verloopt op basis van TTLDraait altijd
AanmakenSchrijf een markdown-bestandSchrijven, compileren, ondertekenen, verpakken
BeveiligingGeen machtigingen nodigSandbox, standaard alles geweigerd

Snel aan de slag

Maak een map in je Nebo-skillsmap met een SKILL.md-bestand:

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

Schrijf een 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 houdt de skillsmap in de gaten met fsnotify. Je skill is meteen beschikbaar — opnieuw starten is niet nodig. Zeg iets dat bij een trigger past, en hij wordt automatisch actief.

Of vraag het Nebo rechtstreeks: "Maak een skill voor het schrijven van blogposts" — Nebo schrijft het SKILL.md-bestand voor je.

SKILL.md-formaat

Elke skill is één SKILL.md-bestand met twee delen: YAML-frontmatter tussen ----markeringen, en een markdown-body (de eigenlijke instructies die in de systeemprompt worden gezet).

VeldVerplichtStandaardBeschrijving
nameJa—Unieke identificatie (wordt de slug)
descriptionJa—Beschrijving van één regel die in de skillcatalogus wordt getoond
versionNee"1.0.0"Semver om updates bij te houden
authorNee—Auteur van de skill
priorityNee0Hoger = eerder gematcht (100+ voor kritieke overschrijvingen)
max_turnsNee4Aantal inactieve beurten voordat de skill automatisch verloopt
triggersNee[]Zinnen die deze skill automatisch activeren (deeltekst, niet hoofdlettergevoelig)
toolsNee[]Tools die deze skill verwacht te gebruiken (ter informatie)
dependenciesNee[]Andere skills die geïnstalleerd moeten zijn
tagsNee[]Voor indeling en vindbaarheid
platformNee[]Ondersteunde platforms: macos, linux, windows (leeg = alle)

Hoe skills actief worden

Skills worden in twee fasen actief: eerst een hint, dan aanroepen.

Fase 1: Triggers matchen — Telkens als een gebruiker een bericht stuurt, doorzoekt Nebo alle geregistreerde skills op passende triggers. Passende skills verschijnen als hints in de systeemprompt. De AI-medewerker ziet de hint en beslist of hij de skill aanroept.

Fase 2: Aanroepen — De AI-medewerker roept een skill aan met:

skill(name: "code-review")

Dit geeft het volledige SKILL.md-sjabloon terug als resultaat van de tool, legt de aanroep vast en plaatst het sjabloon in de volgende beurten opnieuw in de systeemprompt.

TTL en verlopen:

  • Automatisch gematchte skills: 4 inactieve beurten (instelbaar via max_turns)
  • Handmatig geladen skills: 6 inactieve beurten
  • Opnieuw aanroepen zet de timer terug
  • Harde grens: maximaal 4 actieve skills per sessie
  • Tokenbudget: de gezamenlijke inhoud van actieve skills is beperkt tot 16.000 tekens

Skills beheren

De AI-medewerker kan skills beheren met de skill-tool:

ActieBeschrijvingVoorbeeld
catalogAlle beschikbare skills weergevenskill(action: "catalog")
loadActiveren voor deze sessieskill(name: "code-review", action: "load")
unloadEen skill deactiverenskill(name: "code-review", action: "unload")
createEen nieuwe skill op schijf aanmakenskill(action: "create", content: "...")
updateEen bestaande skill bijwerkenskill(name: "my-skill", action: "update", content: "...")
deleteEen skill van schijf verwijderenskill(name: "my-skill", action: "delete")

Goede skills schrijven

Een goed skillsjabloon heeft:

  1. Een duidelijke kop — vertelt de AI-medewerker in welke modus hij zit
  2. Kernprincipes — de gedragsregels waar niet over te onderhandelen valt
  3. Werkwijze — een stapsgewijze aanpak voor veelvoorkomende situaties
  4. Voorbeelden — concrete patronen van gebruikersbericht naar antwoord
  5. Antipatronen — wat je NIET moet doen (modellen leren goed van negatieve voorbeelden)

Tip: Elke skill moet één ding goed doen. Maak geen skill "algemeen programmeren" — maak code-review, debugging en api-design als aparte skills. De AI-medewerker kan er meerdere tegelijk actief hebben.

Meegeleverde skills

Nebo wordt geleverd met skills voor veelvoorkomende toepassingen:

SkillPrioriteitBeschrijving
onboarding100Begroeting van nieuwe gebruikers en profiel verzamelen
best-friend50Persoonlijkheidsskill — ontspannen, loyaal, eerlijk gezegd
debugging25Systematische werkwijze voor debuggen
api-design15Best practices voor het ontwerpen van RESTful API's
code-review10Gestructureerde code-review met ernstniveaus
database-expert10Databaseontwerp, query's, optimalisatie
git-workflow10Git-branches, commits, PR-workflows
security-audit10Beveiligingsanalyse en opsporen van kwetsbaarheden

Ze dienen zowel als handige standaard als als referentie-implementatie om je eigen skills te maken.

Referentie

Proto-bestanden

Proto-bestanden staan in proto/apps/v0/. De SDK's worden geleverd met vooraf gegenereerde code, dus voor normale ontwikkeling heb je protoc niet nodig.

BestandServiceBelangrijkste RPC's
v0/common.proto(alleen berichten)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

Elke service bevat de RPC's HealthCheck en Configure. De SDK handelt beide automatisch af.

Proto-typen voor kanalen

BerichttypeBeschrijving
ChannelSendRequestEnvelop voor uitgaande berichten met message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseBericht-ID van het platform voor threads
InboundMessageEnvelop voor inkomende berichten met alle gemeenschappelijke velden + tijdstempel
MessageSenderIdentiteit van de bot (name, role, botId) — aangevuld door de broker
AttachmentBijlage met bestand/afbeelding/audio (type, url, filename, size)
MessageActionInteractieve knop-/toetsenbordactie (label, callback_id)

Identiteit en rollen van bots

Nebo-bots hebben een identiteitsmodel met drie assen:

  • creature — Wat de bot is (archetype): "Gevatte strateeg", "Nauwgezette onderzoeker"
  • role — Hoe hij zich tot de gebruiker verhoudt (relatie): "Vriend", "COO", "Mentor"
  • vibe — Zijn energie (communicatiestijl): "Relaxed maar met een mening", "Warm en bemoedigend"

Als je kanaalplug-in een uitgaand bericht ontvangt, bevat het veld sender de name en role van de bot. Gebruik die om de weergavenaam voor je platform op te maken. De rol is geen functietitel — hij beschrijft een relatie. "Vriend", "Zoon" en "Mentor" zijn geldige rollen, net als "COO" en "DevLead".