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.
| Status | Talen |
|---|---|
| Ondersteund | Go (aanbevolen), Rust, C/C++, Zig |
| Geweigerd | Python, 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
- Maak
manifest.jsonaan metid,name,version,provides - Schrijf
TOOL.mdwaarin staat hoe de AI-medewerker je tool moet gebruiken - Installeer de SDK (
go get github.com/neboloop/nebo-sdk-go) - Implementeer de handler-interface voor je capability (
ToolHandler,ChannelHandler, enz.) - Registreer de handler en roep
app.Run()aan - Bouw een native binary (
go build -o binary .) - Zet binary + manifest.json + TOOL.md in de map
apps/<your-app-id>/ - 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:
| Veld | Beschrijving |
|---|---|
id | Identificatie in omgekeerde-domeinnotatie (bijv. com.mycompany.myapp) |
name | Leesbare naam |
version | Semver-tekenreeks |
provides | Minstens één capability (zie hieronder) |
Optionele velden:
| Veld | Standaard | Beschrijving |
|---|---|---|
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:
| Capability | gRPC-service | Beschrijving |
|---|---|---|
gateway | GatewayService | Routering van LLM-modellen |
tool:<name> | ToolService | Een tool met een naam voor de AI-medewerker |
channel:<name> | ChannelService | Een berichtenkanaal |
comm | CommService | Communicatie tussen AI-medewerkers |
ui | UIService | Aangepaste UI met HTTP-proxy |
schedule | ScheduleService | Aangepaste planning |
vision | ToolService | Beeldverwerking |
browser | ToolService | Browserautomatisering |
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.
| Voorvoegsel | Voorbeelden | Beschrijving |
|---|---|---|
network: | network:outbound, network:* | Netwerktoegang |
filesystem: | filesystem:read, filesystem:write | Toegang tot het bestandssysteem |
memory: | memory:read, memory:write | Toegang tot het geheugen van de AI-medewerker |
session: | session:read | Gesprekssessies |
tool: | tool:shell, tool:file | Andere tools gebruiken |
shell: | shell:exec | Shell-opdrachten uitvoeren |
channel: | channel:send, channel:* | Kanaalbewerkingen |
comm: | comm:send, comm:* | Communicatie tussen AI-medewerkers |
model: | model:chat | Toegang tot AI-modellen |
user: | user:token | JWT van de gebruiker ontvangen in verzoeken |
schedule: | schedule:create | Beheer van cronjobs |
database: | database:query | Toegang tot de database |
storage: | storage:read, storage:write | Permanente opslag |
context: | context:read | Toegang tot de context van de AI-medewerker |
subagent: | subagent:spawn | Bewerkingen met sub-agents |
lane: | lane:enqueue | Lane-bewerkingen |
notification: | notification:send | Pushmeldingen |
embedding: | embedding:search | Toegang tot vector-embeddings |
skill: | skill:invoke | Skills aanroepen |
advisor: | advisor:consult | Toegang tot het adviseurssysteem |
mcp: | mcp:connect | Toegang tot MCP-servers |
voice: | voice:record | Toegang tot spraak/audio |
browser: | browser:navigate | Browserautomatisering |
oauth: | oauth:google, oauth:* | Toegang tot OAuth-tokens |
settings: | settings:read | Toegang tot instellingen |
capability: | capability:register | Registratie 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".
| Type | Beschrijving |
|---|---|
text | Tekstinvoer op één regel |
password | Gemaskeerde tekstinvoer |
toggle | Booleaanse aan/uit-schakelaar |
select | Vervolgkeuzelijst met vooraf ingestelde opties |
number | Numerieke invoer |
url | URL-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"]
}
]
} | Veld | Beschrijving |
|---|---|
provider | OAuth-provider: "google", "microsoft", "github" |
scopes | Array 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:
| Variabele | Waarde |
|---|---|
NEBO_APP_DIR | Installatiemap van de app |
NEBO_APP_SOCK | Pad naar de Unix-socket die moet worden aangemaakt |
NEBO_APP_ID | App-ID uit het manifest |
NEBO_APP_NAME | App-naam uit het manifest |
NEBO_APP_VERSION | App-versie uit het manifest |
NEBO_APP_DATA | Pad naar de map data/ van de app |
PATH | Systeem-PATH (doorgegeven) |
HOME | Thuismap van de gebruiker (doorgegeven) |
TMPDIR | Tijdelijke 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
- Nebo leest
manifest.jsonen valideert het - Zoekt het uitvoerbare bestand
binaryofappin de app-map - Controleert op een
.quarantined-markering (apps in quarantaine worden niet gestart) - Controle op intrekking (alleen apps die via NeboAI worden verspreid)
- Verificatie van de handtekening (alleen apps die via NeboAI worden verspreid, overgeslagen in dev)
- Validatie van de binary (weigert symlinks, scripts, niet-uitvoerbare en te grote bestanden)
- Ruimt een verouderde socket van een vorige run op
- Maakt de map
data/aan voor opslag in de sandbox - Zet logbestanden per app op (
logs/stdout.log,logs/stderr.log) - Start de binary met een opgeschoonde omgeving en isolatie per procesgroep
- Wacht tot de Unix-socket verschijnt (exponentiële backoff, maximaal 10 seconden)
- Maakt verbinding via gRPC over de Unix-socket
- Maakt gRPC-clients per capability aan op basis van
provides - Voert een gezondheidscontrole uit
- 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:
- Neem altijd een
action-veld op als verplichte string-enum - Voeg alleen een
resource-veld (verplichte string-enum) toe als je tool meerdere verschillende resourcetypes beheert - Alle andere velden zijn parameters die bij een specifieke actie horen
- 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
- Nebo roept
ID()aan om de unieke identificatie van je kanaal op te halen - Nebo roept
Connect()aan met de configuratie uit de instellingen van je app - Nebo opent een
Receive()-stream — je app stuurt inkomende berichten door telkens als een gebruiker de bot een bericht stuurt - Inkomende berichten worden naar de hoofdgesprekslane van de AI-medewerker gerouteerd
- Als de AI-medewerker een bericht wil versturen, roept Nebo
Send()aan met de v1-berichtenvelop - 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"
} | Veld | Type | Beschrijving |
|---|---|---|
message_id | UUID v7 | Unieke ID, op tijd gesorteerd |
channel_id | {type}:{platform_id} | Routeerbare kanaalidentificatie |
sender | object | Identiteit van de bot — naam, rol, botId |
text | string | Berichttekst |
attachments | array | Bestanden, afbeeldingen, audio |
reply_to | UUID v7 | ID van het bovenliggende bericht voor threads |
actions | array | Interactieve knoppen/toetsenborden |
platform_data | bytes | Ondoorzichtige doorgifte voor platformspecifieke functies |
timestamp | ISO 8601 | Wordt 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.
| Veld | Beschrijving |
|---|---|
from | ID van de verzendende medewerker |
to | ID van de ontvangende medewerker |
topic | Onderwerp/kanaal van het bericht |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Berichttekst |
Belangrijkste gedrag:
Registermeldt deze AI-medewerker met zijn capabilities aan op het netwerkSubscribe/Unsubscribebeheren abonnementen op onderwerpenReceivestreamt 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:
| Type | Inhoud | Beschrijving |
|---|---|---|
"text" | Tekstfragment | Streamend teksttoken |
"tool_call" | JSON | Model wil een tool aanroepen |
"thinking" | Tekstfragment | Uitgebreid nadenken/redeneren |
"error" | Foutmelding | Er is iets misgegaan |
"done" | Leeg | Stream 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.
| Pad | Mechanisme | Doel |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Statische bestandsserver | Serveert bestanden uit je map ui/ (SPA-fallback naar index.html) |
ANY /api/v1/apps/{id}/api/* | gRPC-proxy | Stuurt 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 Triggersis 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:
| Bestand | Max. grootte | Beschrijving |
|---|---|---|
manifest.json | 1 MB | Metadata van de app |
binary of app | 500 MB | Uitvoerbaar bestand |
signatures.json | 1 MB | Ed25519-handtekeningen |
TOOL.md | 1 MB | Toolinstructies 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
- Registreer een NeboAI-account via
POST /api/v1/owners/register - Log in om een JWT-token te krijgen:
POST /api/v1/owners/login - 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
- Automatische scan — binaries worden gescand via VirusTotal
- Beoordeling door beheerders — het NeboAI-team beoordeelt metadata, manifest en scanresultaten
- Bij goedkeuring — NeboAI ondertekent de app met Ed25519 en publiceert hem
- Bij afwijzing — je krijgt een reden en kunt het oplossen en opnieuw indienen
Beoogde beoordelingstijd: <24 uur.
Updates uitbrengen
- Werk de versie van de app bij:
PUT /api/v1/developer/apps/{id}met de nieuwe versie - Upload nieuwe binaries voor elk platform
- Dien opnieuw in ter beoordeling
Elke update doorloopt hetzelfde beoordelingsproces. Eerdere versies blijven beschikbaar tot de nieuwe versie is goedgekeurd.
Metadata voor de store
| Veld | Beschrijving |
|---|---|
category | bijv. productivity, communication, developer-tools |
icon | URL van het app-pictogram |
visibility | public of private |
description | Mag langer/uitgebreider zijn dan de beschrijving in het manifest |
Ontwikkelworkflow
Lokale ontwikkeling
Voor lokale ontwikkeling hoef je niets te verpakken:
- Maak de map voor je app aan:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Schrijf je
manifest.jsonen code - Bouw je binary:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo detecteert de nieuwe map automatisch (of start Nebo opnieuw)
- 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.lognaar 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_DATAvoor 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
| Skills | Apps | |
|---|---|---|
| Formaat | Markdown (SKILL.md) | Gecompileerde binary (.napp) |
| Runtime | In de systeemprompt geplaatst | Proces in een sandbox via gRPC |
| Levert | Aanwijzingen voor gedrag, werkwijze | Tools, kanalen, UI-panelen |
| Levensduur | Per sessie, verloopt op basis van TTL | Draait altijd |
| Aanmaken | Schrijf een markdown-bestand | Schrijven, compileren, ondertekenen, verpakken |
| Beveiliging | Geen machtigingen nodig | Sandbox, 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).
| Veld | Verplicht | Standaard | Beschrijving |
|---|---|---|---|
name | Ja | — | Unieke identificatie (wordt de slug) |
description | Ja | — | Beschrijving van één regel die in de skillcatalogus wordt getoond |
version | Nee | "1.0.0" | Semver om updates bij te houden |
author | Nee | — | Auteur van de skill |
priority | Nee | 0 | Hoger = eerder gematcht (100+ voor kritieke overschrijvingen) |
max_turns | Nee | 4 | Aantal inactieve beurten voordat de skill automatisch verloopt |
triggers | Nee | [] | Zinnen die deze skill automatisch activeren (deeltekst, niet hoofdlettergevoelig) |
tools | Nee | [] | Tools die deze skill verwacht te gebruiken (ter informatie) |
dependencies | Nee | [] | Andere skills die geïnstalleerd moeten zijn |
tags | Nee | [] | Voor indeling en vindbaarheid |
platform | Nee | [] | 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:
| Actie | Beschrijving | Voorbeeld |
|---|---|---|
catalog | Alle beschikbare skills weergeven | skill(action: "catalog") |
load | Activeren voor deze sessie | skill(name: "code-review", action: "load") |
unload | Een skill deactiveren | skill(name: "code-review", action: "unload") |
create | Een nieuwe skill op schijf aanmaken | skill(action: "create", content: "...") |
update | Een bestaande skill bijwerken | skill(name: "my-skill", action: "update", content: "...") |
delete | Een skill van schijf verwijderen | skill(name: "my-skill", action: "delete") |
Goede skills schrijven
Een goed skillsjabloon heeft:
- Een duidelijke kop — vertelt de AI-medewerker in welke modus hij zit
- Kernprincipes — de gedragsregels waar niet over te onderhandelen valt
- Werkwijze — een stapsgewijze aanpak voor veelvoorkomende situaties
- Voorbeelden — concrete patronen van gebruikersbericht naar antwoord
- 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:
| Skill | Prioriteit | Beschrijving |
|---|---|---|
onboarding | 100 | Begroeting van nieuwe gebruikers en profiel verzamelen |
best-friend | 50 | Persoonlijkheidsskill — ontspannen, loyaal, eerlijk gezegd |
debugging | 25 | Systematische werkwijze voor debuggen |
api-design | 15 | Best practices voor het ontwerpen van RESTful API's |
code-review | 10 | Gestructureerde code-review met ernstniveaus |
database-expert | 10 | Databaseontwerp, query's, optimalisatie |
git-workflow | 10 | Git-branches, commits, PR-workflows |
security-audit | 10 | Beveiligingsanalyse 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.
| Bestand | Service | Belangrijkste RPC's |
|---|---|---|
v0/common.proto | (alleen berichten) | 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 |
Elke service bevat de RPC's HealthCheck en Configure. De SDK handelt beide automatisch af.
Proto-typen voor kanalen
| Berichttype | Beschrijving |
|---|---|
ChannelSendRequest | Envelop voor uitgaande berichten met message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | Bericht-ID van het platform voor threads |
InboundMessage | Envelop voor inkomende berichten met alle gemeenschappelijke velden + tijdstempel |
MessageSender | Identiteit van de bot (name, role, botId) — aangevuld door de broker |
Attachment | Bijlage met bestand/afbeelding/audio (type, url, filename, size) |
MessageAction | Interactieve 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".