NeboAI
NeboAI
Loslegen

Apps für Nebo bauen

Gib deiner KI neue Superkräfte. Tools, Kanäle, Gateways, UI-Panels — alles, was du dir vorstellen kannst, kompiliert zu einer nativen Binärdatei.

Überblick

Was Nebo ist

Nebo ist ein persönlicher KI-Assistent für den Desktop — ein ständig laufender KI-Mitarbeiter, der dein digitales Leben organisiert. Stell dir Nebo vor wie ein Smartphone: eine leistungsstarke Plattform, die erst durch ihre Apps ihr volles Potenzial entfaltet.

Schon für sich allein ist Nebo ein fähiger KI-Mitarbeiter mit Gedächtnis, Terminplanung, Webbrowsing, Dateiverwaltung und Shell-Zugriff. Der eigentliche Durchbruch sind aber Apps. So wie die Stärke eines Smartphones aus seinem App-Ökosystem kommt, kommt Nebos Stärke aus den Apps, die erweitern, was es kann.

Was Apps sind

Nebo-Apps sind eigenständige, vorkompilierte Bausteine mit enormem Funktionsumfang. Jede App verleiht Nebo eine neue Superkraft — Kalenderverwaltung, E-Mail-Sortierung, Projektverfolgung, Heimautomatisierung, Finanzanalyse — alles, was sich ein Entwickler ausdenken kann.

Apps bieten enorme Leistung auf sehr sichere Weise. Jede App läuft in einer Sandbox, in der Berechtigungen standardmäßig verweigert werden. Sie kann nur auf das zugreifen, was ihr Manifest angibt und der Nutzer freigibt.

Die Bedienung läuft zu 100 % über das Gespräch. Nutzer bedienen Apps nicht über eigene Bildschirme oder Dashboards. Sie sprechen mit Nebo, und Nebo nutzt die Tools der App, um Dinge zu erledigen. „Was steht morgen in meinem Kalender?“ — Nebo ruft die Kalender-App auf. „Erstelle ein Meeting mit Sarah um 3 Uhr nachmittags“ — Nebo ruft die Kalender-App auf. Der Nutzer verlässt das Gespräch nie.

Apps können optional eine Einstellungsoberfläche bereitstellen — ein Konfigurationspanel, das sich in Nebos integriertem Browserfenster öffnet. Hier geben Nutzer API-Schlüssel ein, schalten Funktionen ein und aus und konfigurieren die App. Die Einstellungsoberfläche wird über das settings-Array im Manifest gesteuert (Nebo rendert das Formular automatisch), oder die App liefert über die Fähigkeit ui eine eigene, vollständig angepasste Oberfläche.

Apps ersetzen und erweitern Nebos integrierte Fähigkeiten. Nebo wird mit grundlegenden Plattform-Tools ausgeliefert (lokaler Kalenderzugriff, Screenshots usw.). Wenn du eine Kalender-App installierst, ersetzt sie das integrierte Kalender-Tool und wird zu einer Obermenge — lokal + Cloud + Zusammenführung + Verfügbarkeitsprüfung.

Nur kompilierte Binärdateien

Nebo setzt eine strikte Richtlinie durch, die nur kompilierte Binärdateien zulässt. Alle Apps müssen nativ kompilierte ausführbare Dateien sein.

StatusSprachen
UnterstütztGo (empfohlen), Rust, C/C++, Zig
AbgelehntPython, Node.js, Ruby, Java, .NET, Shell-Skripte

Begründung:

  • Schutz vor Selbstveränderung durch die KI — Ein KI-Mitarbeiter mit Shell-Zugriff könnte das Verhalten eines interpretierten Skripts zur Laufzeit verändern. Kompilierte Binärdateien sind nach dem Signieren unveränderlich.
  • Integrität der Signatur — Ed25519-Signaturen decken die rohen Bytes der Binärdatei ab. Eine signierte Binärdatei lässt sich nicht verändern, ohne die Signatur ungültig zu machen.
  • Durchsetzung der Sandbox — Die Prüfung des Binärformats (ELF/Mach-O/PE-Magic-Bytes) ist eine schnelle, zuverlässige Hürde.

Schnellstart

SDK installieren

Offizielle SDKs übernehmen die gesamte Einrichtung des gRPC-Servers, die Signalverarbeitung und die Protokollanbindung. Du implementierst nur die Handler-Schnittstellen.

Go (empfohlen):

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

Rust (bald verfügbar):

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

C/C++ (bald verfügbar):

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

Verzeichnisstruktur einer App

Apps liegen im Unterverzeichnis apps/ deines Nebo-Datenverzeichnisses:

~/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)

Checkliste für eine minimale App

  1. Erstelle manifest.json mit id, name, version, provides
  2. Schreibe eine TOOL.md, die beschreibt, wie der KI-Mitarbeiter dein Tool nutzen soll
  3. Installiere das SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Implementiere die Handler-Schnittstelle für deine Fähigkeit (ToolHandler, ChannelHandler usw.)
  5. Registriere den Handler und rufe app.Run() auf
  6. Baue eine native Binärdatei (go build -o binary .)
  7. Lege Binärdatei + manifest.json + TOOL.md im Verzeichnis apps/<your-app-id>/ ab
  8. Nebo erkennt sie automatisch und startet sie

Konfiguration

manifest.json

Jede App braucht eine 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
        }
    ]
}

Pflichtfelder:

FeldBeschreibung
idBezeichner in umgekehrter Domain-Schreibweise (z. B. com.mycompany.myapp)
nameLesbarer Name
versionSemver-Zeichenkette
providesMindestens eine Fähigkeit (siehe unten)

Optionale Felder:

FeldStandardBeschreibung
runtime"local""local" oder "remote"
protocol"grpc"Nur "grpc" wird unterstützt
permissions[]Worauf die App Zugriff braucht
description""Wird in der Oberfläche angezeigt
settings[]Konfigurierbare Einstellungen (in der Einstellungsoberfläche dargestellt)
oauth[]Anforderungen an OAuth-Anbieter (siehe Abschnitt OAuth unten)

Fähigkeiten

Gib an, was deine App bereitstellt:

FähigkeitgRPC-DienstBeschreibung
gatewayGatewayServiceRouting zu LLM-Modellen
tool:<name>ToolServiceEin benanntes Tool für den KI-Mitarbeiter
channel:<name>ChannelServiceEin Messaging-Kanal
commCommServiceKommunikation zwischen KI-Mitarbeitern
uiUIServiceEigene Oberfläche mit HTTP-Proxy
scheduleScheduleServiceEigene Terminplanung
visionToolServiceBildverarbeitung
browserToolServiceBrowser-Automatisierung

Eine App kann mehrere Fähigkeiten bereitstellen. Zum Beispiel könnte eine App sowohl ein Tool als auch ein UI-Panel bereitstellen.

Berechtigungen

Berechtigungen steuern, worauf die App zugreifen kann. Standardmäßig ist alles verweigert — was nicht angegeben ist, kann die App nicht nutzen.

PräfixBeispieleBeschreibung
network:network:outbound, network:*Netzwerkzugriff
filesystem:filesystem:read, filesystem:writeZugriff auf das Dateisystem
memory:memory:read, memory:writeZugriff auf das Gedächtnis des KI-Mitarbeiters
session:session:readGesprächssitzungen
tool:tool:shell, tool:fileAndere Tools nutzen
shell:shell:execAusführung von Shell-Befehlen
channel:channel:send, channel:*Kanal-Operationen
comm:comm:send, comm:*Kommunikation zwischen KI-Mitarbeitern
model:model:chatZugriff auf KI-Modelle
user:user:tokenNutzer-JWT in Anfragen empfangen
schedule:schedule:createVerwaltung von Cron-Jobs
database:database:queryDatenbankzugriff
storage:storage:read, storage:writeDauerhafter Speicher
context:context:readZugriff auf den Kontext des KI-Mitarbeiters
subagent:subagent:spawnOperationen mit Sub-Agenten
lane:lane:enqueueLane-Operationen
notification:notification:sendPush-Benachrichtigungen
embedding:embedding:searchZugriff auf Vektor-Embeddings
skill:skill:invokeAufruf von Skills
advisor:advisor:consultZugriff auf das Berater-System
mcp:mcp:connectZugriff auf MCP-Server
voice:voice:recordSprach- und Audiozugriff
browser:browser:navigateBrowser-Automatisierung
oauth:oauth:google, oauth:*Zugriff auf OAuth-Tokens
settings:settings:readZugriff auf Einstellungen
capability:capability:registerRegistrierung von Fähigkeiten

Platzhalter-Berechtigungen werden unterstützt: network:* passt auf jede Berechtigungsprüfung für network:.

Einstellungen

Einstellungen erscheinen in der Nebo-Oberfläche im Einstellungsbereich der App. Nebo speichert sie in der Datenbank und sendet sie bei Änderungen über den RPC Configure an deine App.

Dein Einstellungsschema ist Teil des Eintrags im NeboAI-App-Store. Apps mit nicht konfigurierten Pflichteinstellungen zeigen in der Oberfläche das Abzeichen „Einrichtung nötig“.

TypBeschreibung
textEinzeiliges Textfeld
passwordMaskiertes Textfeld
toggleEin/Aus-Schalter
selectDropdown mit vordefinierten Optionen
numberZahleneingabe
urlURL-Eingabe mit Validierung
{
    "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-Anforderungen

Apps können Anforderungen an OAuth-Anbieter angeben. Nebos OAuth-Broker übernimmt den gesamten Ablauf — Apps erhalten Tokens automatisch über den RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
FeldBeschreibung
providerOAuth-Anbieter: "google", "microsoft", "github"
scopesArray der OAuth-Scopes, die die App benötigt

Wenn der Nutzer die App installiert, fordert Nebo ihn auf, die benötigten OAuth-Scopes zu autorisieren. Die App erhält aktualisierte Tokens über den RPC Configure, ohne den OAuth-Ablauf selbst abzuwickeln.

Umgebungsvariablen

Dein App-Prozess erhält eine bereinigte Umgebung. Alle Geheimnisse werden entfernt. Du bekommst:

VariableWert
NEBO_APP_DIRInstallationsverzeichnis der App
NEBO_APP_SOCKPfad zum anzulegenden Unix-Socket
NEBO_APP_IDApp-ID aus dem Manifest
NEBO_APP_NAMEApp-Name aus dem Manifest
NEBO_APP_VERSIONApp-Version aus dem Manifest
NEBO_APP_DATAPfad zum Verzeichnis data/ der App
PATHSystem-PATH (durchgereicht)
HOMEHome-Verzeichnis des Nutzers (durchgereicht)
TMPDIRTemp-Verzeichnis (durchgereicht)

Wichtig: Deine Binärdatei muss einen gRPC-Server erstellen, der auf dem Unix-Socket unter NEBO_APP_SOCK lauscht. Nebo wartet bis zu 10 Sekunden darauf, dass dieser Socket erscheint.

Startablauf einer App

  1. Nebo liest manifest.json und validiert sie
  2. Sucht die ausführbare Datei binary oder app im App-Verzeichnis
  3. Prüft auf die Markierung .quarantined (startet keine Apps in Quarantäne)
  4. Prüfung auf Widerruf (nur über NeboAI verteilte Apps)
  5. Signaturprüfung (nur über NeboAI verteilte Apps, im Entwicklungsmodus übersprungen)
  6. Prüfung der Binärdatei (lehnt Symlinks, Skripte, nicht ausführbare und übergroße Dateien ab)
  7. Räumt veraltete Sockets aus dem vorherigen Lauf auf
  8. Legt das Verzeichnis data/ für den Speicher in der Sandbox an
  9. Richtet Logdateien pro App ein (logs/stdout.log, logs/stderr.log)
  10. Startet die Binärdatei mit bereinigter Umgebung und isolierter Prozessgruppe
  11. Wartet, bis der Unix-Socket erscheint (exponentielles Backoff, maximal 10 Sekunden)
  12. Verbindet sich per gRPC über den Unix-Socket
  13. Erstellt fähigkeitsspezifische gRPC-Clients anhand von provides
  14. Führt einen Health-Check aus
  15. Registriert die Fähigkeiten beim KI-Mitarbeiter (Tools, Gateway, Comm usw.)

Tool-Apps

Gib in deinem Manifest "provides": ["tool:my_tool_name"] an.

Das STRAP-Muster

Alle Nebo-Tool-Apps müssen für ihr Schema und das Routing der Ausführung das STRAP-Muster (Single Tool Resource Action Pattern) verwenden. Es ist dasselbe Muster, mit dem Nebo intern 35+ einzelne Tools zu 4 Domänen-Tools zusammenfasst — und so den LLM-Kontext-Overhead um ~80 % senkt.

Grundidee: Statt mehrere Tools zu registrieren (get_events, check_availability, suggest_slots), registrierst du EIN Tool mit den Feldern action (und optional resource), die an den richtigen Handler weiterleiten.

Beispiel mit einer Ressource (Kalender):

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

Beispiel mit mehreren Ressourcen (Projektmanager):

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

Schema-Regeln:

  1. Füge immer ein Feld action als erforderliches String-Enum hinzu
  2. Füge ein Feld resource (erforderliches String-Enum) nur hinzu, wenn dein Tool mehrere unterschiedliche Ressourcentypen verwaltet
  3. Alle anderen Felder sind aktionsspezifische Parameter
  4. Die Beschreibung des Enums action sollte alle verfügbaren Aktionen auflisten

Warum STRAP wichtig ist:

  • LLMs lernen das Routing-Muster über action einmal und übertragen es auf alle Operationen
  • Tool-Definitionen belegen ~6 % des Kontexts — STRAP senkt das um 80 %
  • Neue Operationen sind nur zusätzliche Enum-Werte, keine neuen Tool-Registrierungen
  • Funktioniert gleich mit gehosteten und lokalen Modellen

Go-Beispiel — Rechner-Tool

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

Bauen und installieren:

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-Beispiel

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-Beispiel

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

Kanal-Apps

Gib "provides": ["channel:my_channel"] und "permissions": ["channel:send"] an.

Kanal-Apps verbinden externe Messaging-Plattformen (Telegram, Discord, Slack usw.) mit Nebos KI-Mitarbeiter. Wenn ein Nutzer auf der externen Plattform eine Nachricht sendet, streamt deine App sie über Receive an Nebo. Wenn der KI-Mitarbeiter antworten möchte, ruft Nebo das Send deiner App auf.

So funktioniert es

  1. Nebo ruft ID() auf, um die eindeutige Kennung deines Kanals zu erhalten
  2. Nebo ruft Connect() mit der Konfiguration aus den Einstellungen deiner App auf
  3. Nebo öffnet einen Receive()-Stream — deine App sendet eingehende Nachrichten, sobald ein Nutzer dem Bot schreibt
  4. Eingehende Nachrichten werden an die Haupt-Gesprächslane des KI-Mitarbeiters weitergeleitet
  5. Wenn der KI-Mitarbeiter eine Nachricht senden möchte, ruft Nebo Send() mit dem v1-Nachrichtenumschlag auf
  6. Beim Herunterfahren ruft Nebo Disconnect() auf

v1-Nachrichtenumschlag

Alle Kanalnachrichten — eingehend wie ausgehend — verwenden den gemeinsamen Nachrichtenumschlag:

{
  "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"
}
FeldTypBeschreibung
message_idUUID v7Zeitlich geordnete eindeutige ID
channel_id{type}:{platform_id}Routbare Kanalkennung
senderobjectBot-Identität — name, role, botId
textstringNachrichtentext
attachmentsarrayDateien, Bilder, Audio
reply_toUUID v7ID der übergeordneten Nachricht für Threads
actionsarrayInteraktive Buttons/Tastaturen
platform_databytesOpake Durchreichung für plattformspezifische Funktionen
timestampISO 8601Wird vom Publisher gesetzt

Zweischichtiges Design: Die gemeinsamen Felder (text, attachments, reply_to, actions) decken 90 % der von Mitarbeitern ausgelösten Nachrichten ab. Plattformspezifische Funktionen gehören in platform_data — dein Plugin übersetzt sie in das native Format der Plattform und zurück.

Gesprächs-Streams

Kanalnachrichten laufen zur Isolation über eigene Gesprächs-Streams pro Kanal:

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

Go-Beispiel — Telegram-Kanal

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

Weitere Fähigkeiten

Comm-App

Gib "provides": ["comm"] und "permissions": ["comm:*"] an. Comm-Apps ermöglichen die Kommunikation zwischen KI-Mitarbeitern.

FeldBeschreibung
fromID des sendenden Mitarbeiters
toID des empfangenden Mitarbeiters
topicThema/Kanal der Nachricht
type"message", "mention", "proposal", "command", "info", "task"
contentNachrichtentext

Wichtiges Verhalten:

  • Register meldet diesen KI-Mitarbeiter mit seinen Fähigkeiten im Netzwerk an
  • Subscribe/Unsubscribe verwalten Themen-Abonnements
  • Receive streamt eingehende Nachrichten (Server-Streaming, wie bei Kanälen)
  • Es kann immer nur eine Comm-App gleichzeitig aktiv sein

Gateway-App

Eine Gateway-App leitet LLM-Anfragen an Modelle weiter. Gib "provides": ["gateway"] und "permissions": ["network:outbound", "user:token"] an.

GatewayRequest enthält Nachrichten, Tools, System-Prompt, maximale Tokens, Temperatur und einen UserContext (JWT-Token, wenn die Berechtigung user:token erteilt ist).

GatewayEvent-Typen:

TypInhaltBeschreibung
"text"TextabschnittGestreamtes Text-Token
"tool_call"JSONDas Modell möchte ein Tool aufrufen
"thinking"TextabschnittErweitertes Denken/Schlussfolgern
"error"FehlermeldungEtwas ist schiefgelaufen
"done"LeerDer Stream ist abgeschlossen

UI-App

Eine UI-App stellt eine eigene Konfigurationsoberfläche bereit, die sich in Nebos integriertem Browserfenster öffnet. Gib "provides": ["ui"] an. Anders als das automatische Einstellungsformular (das Nebo aus deinem settings-Manifest rendert) liefert eine UI-App ihr eigenes, vollständiges HTML/CSS/JS-Frontend aus.

Deine App bringt ein Verzeichnis ui/ mit statischen Web-Assets mit (HTML, CSS, JS — typischerweise eine SPA mit index.html). Nebo liefert diese Dateien direkt aus und leitet API-Aufrufe per gRPC an deine App weiter.

PfadMechanismusZweck
GET /api/v1/apps/{id}/ui/*Statischer DateiserverLiefert Dateien aus deinem Verzeichnis ui/ aus (SPA-Fallback auf index.html)
ANY /api/v1/apps/{id}/api/*gRPC-ProxyLeitet HTTP-Anfragen an UIService.HandleRequest() deiner App weiter

Das SDK kapselt einen standardmäßigen net/http.ServeMux, sodass du ganz normale Go-HTTP-Handler schreibst — das SDK übernimmt die gRPC-Anbindung automatisch.

Go-Beispiel — Dashboard-Oberfläche:

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

Deine ui/index.html würde fetch-Aufrufe an /api/v1/apps/com.example.dashboard/api/status senden, die an deinen mux-Handler weitergeleitet werden.

Zeitplan-App

Eine Zeitplan-App ersetzt Nebos integrierten Cron-Scheduler. Gib "provides": ["schedule"] und "permissions": ["schedule:create"] an.

Sobald deine Zeitplan-App startet, leitet Nebo die gesamte Terminplanung über deine App statt über die Standard-Cron-Engine. Stürzt deine App ab, greift Nebo automatisch auf die integrierte Engine zurück.

  • Deine App verwaltet den Zustand der Zeitpläne selbst — Nebo speichert keine Zeitpläne in der eigenen Datenbank, solange eine Zeitplan-App aktiv ist
  • Standard-CRUD: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers ist ein Server-Streaming-RPC — deine App sendet eine Trigger-Nachricht, sobald ein Zeitplan auslöst
  • Es kann immer nur eine Zeitplan-App gleichzeitig aktiv sein

Apps mit mehreren Fähigkeiten

Eine App kann mehrere Fähigkeiten bereitstellen. Zum Beispiel eine Dashboard-App mit Tool und Oberfläche:

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

Paketierung

.napp-Format

Für die Verteilung über NeboAI packst du deine App als .napp-Datei (ein tar.gz-Archiv):

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

Erforderliche Dateien:

DateiMax. GrößeBeschreibung
manifest.json1 MBApp-Metadaten
binary oder app500 MBAusführbare Datei
signatures.json1 MBEd25519-Signaturen
TOOL.md1 MBTool-Anweisungen für den KI-Mitarbeiter

Sicherheitsregeln beim Entpacken:

  • Keine Pfad-Traversierung (../ wird abgelehnt)
  • Keine Symlinks (werden abgelehnt)
  • Keine absoluten Pfade (werden abgelehnt)
  • Nur zugelassene Dateinamen werden akzeptiert

Signaturen

NeboAI signiert Apps mit Ed25519. Das Format von 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>"
}

Im Entwicklungsmodus (keine NeboAI-URL konfiguriert) wird die Signaturprüfung komplett übersprungen. Für die lokale Entwicklung brauchst du keine signatures.json.

Veröffentlichen

Sobald deine App lokal funktioniert, veröffentlichst du sie über NeboAI, damit sie alle Nebo-Nutzer erreicht.

Entwicklerkonto einrichten

  1. Registriere ein NeboAI-Konto unter POST /api/v1/owners/register
  2. Melde dich an, um ein JWT-Token zu erhalten: POST /api/v1/owners/login
  3. Erstelle ein Entwicklerkonto: POST /api/v1/developer/accounts

Ablauf der Einreichung

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

Schritt 1: App erstellen

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

Schritt 2: Plattform-Binärdateien hochladen

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"

Lade pro Plattform eine Binärdatei hoch: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Schritt 3: Zur Prüfung einreichen

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

Prüfprozess

  1. Automatischer Scan — Binärdateien werden mit VirusTotal gescannt
  2. Prüfung durch Admins — das NeboAI-Team prüft Metadaten, Manifest und Scan-Ergebnisse
  3. Bei Freigabe — NeboAI signiert die App mit Ed25519 und veröffentlicht sie
  4. Bei Ablehnung — du erhältst eine Begründung und kannst nachbessern und erneut einreichen

Angestrebte Prüfdauer: <24 Stunden.

Updates veröffentlichen

  1. Aktualisiere die Version der App: PUT /api/v1/developer/apps/{id} mit der neuen Version
  2. Lade für jede Plattform neue Binärdateien hoch
  3. Reiche erneut zur Prüfung ein

Jedes Update durchläuft denselben Prüfprozess. Frühere Versionen bleiben verfügbar, bis die neue Version freigegeben ist.

Store-Metadaten

FeldBeschreibung
categoryz. B. productivity, communication, developer-tools
iconURL des App-Icons
visibilitypublic oder private
descriptionDarf länger und ausführlicher sein als die Beschreibung im Manifest

Entwicklungs-Workflow

Lokale Entwicklung

Für die lokale Entwicklung ist keine Paketierung nötig:

  1. Erstelle dein App-Verzeichnis:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Schreibe deine manifest.json und deinen Code
  3. Baue deine Binärdatei:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo erkennt das neue Verzeichnis automatisch (oder starte Nebo neu)
  5. Baue nach Codeänderungen die Binärdatei neu — der Datei-Watcher startet die App dann neu

Logs ansehen

Stdout/stderr der App werden in Logdateien pro App erfasst:

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

Dauerhafte Daten

Nutze das Verzeichnis data/ (auch als Umgebungsvariable NEBO_APP_DATA verfügbar) für alle Dateien, die deine App dauerhaft speichern muss. Dieses Verzeichnis übersteht App-Updates und Quarantäne.

Tipps zur Fehlersuche

  • Wenn deine App nicht startet, sieh in logs/stderr.log nach Fehlern
  • Stelle sicher, dass die Binärdatei ausführbar ist (chmod +x binary)
  • Stelle sicher, dass du auf dem Unix-Socket-Pfad aus NEBO_APP_SOCK lauschst
  • Der Socket muss innerhalb von 10 Sekunden nach dem Start bereit sein
  • Nutze NEBO_APP_DATA für die Speicherung, keine fest codierten Pfade
  • Gib Debug-Logs auf stderr aus (sie landen in logs/stderr.log)

Überprüfen

# 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

Deinstallieren

nebo apps uninstall com.example.myapp

Skills

Was Skills sind

Skills sind Anweisungssätze, die bestimmen, wie sich Nebo in einem Gespräch verhält. Wenn ein Skill aktiv ist, wird sein Inhalt direkt in den System-Prompt eingefügt — und lenkt Tonfall, Vorgehensweise, Fachwissen und Tool-Nutzung des KI-Mitarbeiters für diese Sitzung.

Skills sind kein Code. Es sind Markdown-Dokumente mit YAML-Metadaten. Keine Kompilierung, keine Binärdatei, kein gRPC. Ein Skill ist eine SKILL.md-Datei in einem Verzeichnis. Das ist alles.

Skills sind kontextbezogen und vorübergehend. Sie werden aktiv, wenn sie relevant sind (über Trigger-Abgleich oder manuelles Laden), bleiben für ein paar Runden bestehen und laufen ab, wenn sie nicht mehr gebraucht werden. So bleibt der Kontext des KI-Mitarbeiters schlank — im Prompt steht nur die Anleitung, die gerade zählt.

Skills ergänzen Apps. Apps liefern ausführbare Fähigkeiten (Tools, Kanäle, Gateways). Skills liefern Anleitung zur Orchestrierung — wie man diese Tools wirksam einsetzt. Eine Kalender-App gibt Nebo die Möglichkeit, Termine zu lesen und zu schreiben. Ein Skill zur Meeting-Vorbereitung sagt Nebo, wie es sich mit dieser Kalender-App, E-Mail und Websuche zusammen auf Meetings vorbereitet.

Skills und Apps im Vergleich

SkillsApps
FormatMarkdown (SKILL.md)Kompilierte Binärdatei (.napp)
LaufzeitIn den System-Prompt eingefügtProzess in der Sandbox über gRPC
LiefertVerhaltensanleitung, VorgehensweiseTools, Kanäle, UI-Panels
LebensdauerAuf die Sitzung begrenzt, Ablauf per TTLLäuft ständig
ErstellungEine Markdown-Datei schreibenSchreiben, kompilieren, signieren, paketieren
SicherheitKeine Berechtigungen nötigSandbox mit standardmäßig verweigerten Berechtigungen

Schnellstart

Lege in deinem Nebo-Skills-Ordner ein Verzeichnis mit einer SKILL.md-Datei an:

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

Schreibe eine 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 überwacht das Skills-Verzeichnis mit fsnotify. Dein Skill ist sofort verfügbar — kein Neustart nötig. Sag etwas, das zu einem Trigger passt, und er wird automatisch aktiv.

Oder bitte Nebo direkt darum: „Erstelle einen Skill zum Schreiben von Blogbeiträgen“ — Nebo schreibt die SKILL.md-Datei für dich.

SKILL.md-Format

Jeder Skill ist eine einzelne SKILL.md-Datei aus zwei Teilen: YAML-Frontmatter zwischen ----Markierungen und einem Markdown-Hauptteil (die eigentlichen Anweisungen, die in den System-Prompt eingefügt werden).

FeldErforderlichStandardBeschreibung
nameJa—Eindeutige Kennung (wird zum Slug)
descriptionJa—Einzeilige Beschreibung, die im Skill-Katalog angezeigt wird
versionNein"1.0.0"Semver zum Nachverfolgen von Updates
authorNein—Autor des Skills
priorityNein0Höher = wird zuerst abgeglichen (100+ für kritische Überschreibungen)
max_turnsNein4Runden ohne Aktivität bis zum automatischen Ablauf
triggersNein[]Formulierungen, die diesen Skill automatisch aktivieren (Teilstring-Abgleich ohne Beachtung der Groß-/Kleinschreibung)
toolsNein[]Tools, die dieser Skill voraussichtlich nutzt (zur Information)
dependenciesNein[]Andere Skills, die installiert sein müssen
tagsNein[]Zur Kategorisierung und Auffindbarkeit
platformNein[]Unterstützte Plattformen: macos, linux, windows (leer = alle)

So werden Skills aktiv

Skills folgen einem zweistufigen Aktivierungsmodell: erst Hinweis, dann Aufruf.

Phase 1: Trigger-Abgleich — Jedes Mal, wenn ein Nutzer eine Nachricht sendet, durchsucht Nebo alle registrierten Skills nach passenden Triggern. Passende Skills erscheinen als Hinweise im System-Prompt. Der KI-Mitarbeiter sieht den Hinweis und entscheidet, ob er den Skill aufruft.

Phase 2: Aufruf — Der KI-Mitarbeiter ruft einen Skill so auf:

skill(name: "code-review")

Das gibt die vollständige SKILL.md-Vorlage als Tool-Ergebnis zurück, protokolliert den Aufruf und fügt die Vorlage in den folgenden Runden erneut in den System-Prompt ein.

TTL und Ablauf:

  • Automatisch zugeordnete Skills: 4 Runden ohne Aktivität (konfigurierbar über max_turns)
  • Manuell geladene Skills: 6 Runden ohne Aktivität
  • Ein erneuter Aufruf setzt den Zähler zurück
  • Feste Obergrenze: maximal 4 aktive Skills pro Sitzung
  • Token-Budget: der Inhalt aller aktiven Skills zusammen ist auf 16.000 Zeichen begrenzt

Skills verwalten

Der KI-Mitarbeiter kann Skills über das Tool skill verwalten:

AktionBeschreibungBeispiel
catalogAlle verfügbaren Skills auflistenskill(action: "catalog")
loadFür diese Sitzung aktivierenskill(name: "code-review", action: "load")
unloadEinen Skill deaktivierenskill(name: "code-review", action: "unload")
createEinen neuen Skill auf der Festplatte anlegenskill(action: "create", content: "...")
updateEinen bestehenden Skill aktualisierenskill(name: "my-skill", action: "update", content: "...")
deleteEinen Skill von der Festplatte löschenskill(name: "my-skill", action: "delete")

Gute Skills schreiben

Eine gute Skill-Vorlage hat:

  1. Eine klare Überschrift — sagt dem KI-Mitarbeiter, in welchem Modus er ist
  2. Kernprinzipien — die nicht verhandelbaren Verhaltensregeln
  3. Vorgehensweise — ein Schritt-für-Schritt-Ansatz für häufige Situationen
  4. Beispiele — konkrete Muster von Nutzernachricht zu Antwort
  5. Anti-Muster — was man NICHT tun sollte (Modelle lernen gut aus negativen Beispielen)

Tipp: Jeder Skill sollte eine Sache gut machen. Erstelle keinen Skill für „allgemeines Programmieren“ — erstelle code-review, debugging und api-design als getrennte Skills. Der KI-Mitarbeiter kann mehrere gleichzeitig aktiv haben.

Mitgelieferte Skills

Nebo wird mit Skills für häufige Anwendungsfälle ausgeliefert:

SkillPrioritätBeschreibung
onboarding100Begrüßung neuer Nutzer und Erfassung des Profils
best-friend50Persönlichkeits-Skill — locker, loyal, ehrliche Worte
debugging25Systematische Methode zur Fehlersuche
api-design15Best Practices für das Design von REST-APIs
code-review10Strukturiertes Code-Review mit Schweregraden
database-expert10Datenbankdesign, Abfragen, Optimierung
git-workflow10Git-Branching, Commits, PR-Workflows
security-audit10Sicherheitsanalyse und Erkennung von Schwachstellen

Sie dienen sowohl als nützliche Standards als auch als Referenzimplementierungen für deine eigenen Skills.

Referenz

Proto-Dateien

Proto-Dateien liegen in proto/apps/v0/. Die SDKs bringen vorgenerierten Code mit, sodass du für die normale Entwicklung kein protoc brauchst.

DateiDienstWichtige RPCs
v0/common.proto(nur Nachrichten)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

Jeder Dienst enthält die RPCs HealthCheck und Configure. Das SDK übernimmt beide automatisch.

Proto-Typen für Kanäle

NachrichtentypBeschreibung
ChannelSendRequestUmschlag für ausgehende Nachrichten mit message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseNachrichten-ID der Plattform für Threads
InboundMessageUmschlag für eingehende Nachrichten mit allen gemeinsamen Feldern + Zeitstempel
MessageSenderBot-Identität (name, role, botId) — vom Broker angereichert
AttachmentAnhang mit Datei/Bild/Audio (type, url, filename, size)
MessageActionInteraktive Button-/Tastatur-Aktion (label, callback_id)

Bot-Identität und Rollen

Nebo-Bots haben ein Identitätsmodell mit drei Achsen:

  • creature — Was der Bot ist (Archetyp): „Schlagfertiger Stratege“, „Akribischer Rechercheur“
  • role — Wie er zum Nutzer steht (Beziehung): „Freund“, „COO“, „Mentor“
  • vibe — Seine Energie (Kommunikationsstil): „Entspannt, aber mit Meinung“, „Herzlich und ermutigend“

Wenn dein Kanal-Plugin eine ausgehende Nachricht empfängt, enthält das Feld sender den name und die role des Bots. Nutze das, um den Anzeigenamen für deine Plattform zu formatieren. Die Rolle ist keine Berufsbezeichnung — sie beschreibt eine Beziehung. „Freund“, „Sohn“ und „Mentor“ sind genauso gültige Rollen wie „COO“ und „DevLead“.