Ü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.
| Status | Sprachen |
|---|---|
| Unterstützt | Go (empfohlen), Rust, C/C++, Zig |
| Abgelehnt | Python, 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
- Erstelle
manifest.jsonmitid,name,version,provides - Schreibe eine
TOOL.md, die beschreibt, wie der KI-Mitarbeiter dein Tool nutzen soll - Installiere das SDK (
go get github.com/neboloop/nebo-sdk-go) - Implementiere die Handler-Schnittstelle für deine Fähigkeit (
ToolHandler,ChannelHandlerusw.) - Registriere den Handler und rufe
app.Run()auf - Baue eine native Binärdatei (
go build -o binary .) - Lege Binärdatei + manifest.json + TOOL.md im Verzeichnis
apps/<your-app-id>/ab - 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:
| Feld | Beschreibung |
|---|---|
id | Bezeichner in umgekehrter Domain-Schreibweise (z. B. com.mycompany.myapp) |
name | Lesbarer Name |
version | Semver-Zeichenkette |
provides | Mindestens eine Fähigkeit (siehe unten) |
Optionale Felder:
| Feld | Standard | Beschreibung |
|---|---|---|
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ähigkeit | gRPC-Dienst | Beschreibung |
|---|---|---|
gateway | GatewayService | Routing zu LLM-Modellen |
tool:<name> | ToolService | Ein benanntes Tool für den KI-Mitarbeiter |
channel:<name> | ChannelService | Ein Messaging-Kanal |
comm | CommService | Kommunikation zwischen KI-Mitarbeitern |
ui | UIService | Eigene Oberfläche mit HTTP-Proxy |
schedule | ScheduleService | Eigene Terminplanung |
vision | ToolService | Bildverarbeitung |
browser | ToolService | Browser-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äfix | Beispiele | Beschreibung |
|---|---|---|
network: | network:outbound, network:* | Netzwerkzugriff |
filesystem: | filesystem:read, filesystem:write | Zugriff auf das Dateisystem |
memory: | memory:read, memory:write | Zugriff auf das Gedächtnis des KI-Mitarbeiters |
session: | session:read | Gesprächssitzungen |
tool: | tool:shell, tool:file | Andere Tools nutzen |
shell: | shell:exec | Ausführung von Shell-Befehlen |
channel: | channel:send, channel:* | Kanal-Operationen |
comm: | comm:send, comm:* | Kommunikation zwischen KI-Mitarbeitern |
model: | model:chat | Zugriff auf KI-Modelle |
user: | user:token | Nutzer-JWT in Anfragen empfangen |
schedule: | schedule:create | Verwaltung von Cron-Jobs |
database: | database:query | Datenbankzugriff |
storage: | storage:read, storage:write | Dauerhafter Speicher |
context: | context:read | Zugriff auf den Kontext des KI-Mitarbeiters |
subagent: | subagent:spawn | Operationen mit Sub-Agenten |
lane: | lane:enqueue | Lane-Operationen |
notification: | notification:send | Push-Benachrichtigungen |
embedding: | embedding:search | Zugriff auf Vektor-Embeddings |
skill: | skill:invoke | Aufruf von Skills |
advisor: | advisor:consult | Zugriff auf das Berater-System |
mcp: | mcp:connect | Zugriff auf MCP-Server |
voice: | voice:record | Sprach- und Audiozugriff |
browser: | browser:navigate | Browser-Automatisierung |
oauth: | oauth:google, oauth:* | Zugriff auf OAuth-Tokens |
settings: | settings:read | Zugriff auf Einstellungen |
capability: | capability:register | Registrierung 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“.
| Typ | Beschreibung |
|---|---|
text | Einzeiliges Textfeld |
password | Maskiertes Textfeld |
toggle | Ein/Aus-Schalter |
select | Dropdown mit vordefinierten Optionen |
number | Zahleneingabe |
url | URL-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"]
}
]
} | Feld | Beschreibung |
|---|---|
provider | OAuth-Anbieter: "google", "microsoft", "github" |
scopes | Array 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:
| Variable | Wert |
|---|---|
NEBO_APP_DIR | Installationsverzeichnis der App |
NEBO_APP_SOCK | Pfad zum anzulegenden Unix-Socket |
NEBO_APP_ID | App-ID aus dem Manifest |
NEBO_APP_NAME | App-Name aus dem Manifest |
NEBO_APP_VERSION | App-Version aus dem Manifest |
NEBO_APP_DATA | Pfad zum Verzeichnis data/ der App |
PATH | System-PATH (durchgereicht) |
HOME | Home-Verzeichnis des Nutzers (durchgereicht) |
TMPDIR | Temp-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
- Nebo liest
manifest.jsonund validiert sie - Sucht die ausführbare Datei
binaryoderappim App-Verzeichnis - Prüft auf die Markierung
.quarantined(startet keine Apps in Quarantäne) - Prüfung auf Widerruf (nur über NeboAI verteilte Apps)
- Signaturprüfung (nur über NeboAI verteilte Apps, im Entwicklungsmodus übersprungen)
- Prüfung der Binärdatei (lehnt Symlinks, Skripte, nicht ausführbare und übergroße Dateien ab)
- Räumt veraltete Sockets aus dem vorherigen Lauf auf
- Legt das Verzeichnis
data/für den Speicher in der Sandbox an - Richtet Logdateien pro App ein (
logs/stdout.log,logs/stderr.log) - Startet die Binärdatei mit bereinigter Umgebung und isolierter Prozessgruppe
- Wartet, bis der Unix-Socket erscheint (exponentielles Backoff, maximal 10 Sekunden)
- Verbindet sich per gRPC über den Unix-Socket
- Erstellt fähigkeitsspezifische gRPC-Clients anhand von
provides - Führt einen Health-Check aus
- 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:
- Füge immer ein Feld
actionals erforderliches String-Enum hinzu - Füge ein Feld
resource(erforderliches String-Enum) nur hinzu, wenn dein Tool mehrere unterschiedliche Ressourcentypen verwaltet - Alle anderen Felder sind aktionsspezifische Parameter
- Die Beschreibung des Enums
actionsollte alle verfügbaren Aktionen auflisten
Warum STRAP wichtig ist:
- LLMs lernen das Routing-Muster über
actioneinmal 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
- Nebo ruft
ID()auf, um die eindeutige Kennung deines Kanals zu erhalten - Nebo ruft
Connect()mit der Konfiguration aus den Einstellungen deiner App auf - Nebo öffnet einen
Receive()-Stream — deine App sendet eingehende Nachrichten, sobald ein Nutzer dem Bot schreibt - Eingehende Nachrichten werden an die Haupt-Gesprächslane des KI-Mitarbeiters weitergeleitet
- Wenn der KI-Mitarbeiter eine Nachricht senden möchte, ruft Nebo
Send()mit dem v1-Nachrichtenumschlag auf - 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"
} | Feld | Typ | Beschreibung |
|---|---|---|
message_id | UUID v7 | Zeitlich geordnete eindeutige ID |
channel_id | {type}:{platform_id} | Routbare Kanalkennung |
sender | object | Bot-Identität — name, role, botId |
text | string | Nachrichtentext |
attachments | array | Dateien, Bilder, Audio |
reply_to | UUID v7 | ID der übergeordneten Nachricht für Threads |
actions | array | Interaktive Buttons/Tastaturen |
platform_data | bytes | Opake Durchreichung für plattformspezifische Funktionen |
timestamp | ISO 8601 | Wird 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.
| Feld | Beschreibung |
|---|---|
from | ID des sendenden Mitarbeiters |
to | ID des empfangenden Mitarbeiters |
topic | Thema/Kanal der Nachricht |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Nachrichtentext |
Wichtiges Verhalten:
Registermeldet diesen KI-Mitarbeiter mit seinen Fähigkeiten im Netzwerk anSubscribe/Unsubscribeverwalten Themen-AbonnementsReceivestreamt 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:
| Typ | Inhalt | Beschreibung |
|---|---|---|
"text" | Textabschnitt | Gestreamtes Text-Token |
"tool_call" | JSON | Das Modell möchte ein Tool aufrufen |
"thinking" | Textabschnitt | Erweitertes Denken/Schlussfolgern |
"error" | Fehlermeldung | Etwas ist schiefgelaufen |
"done" | Leer | Der 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.
| Pfad | Mechanismus | Zweck |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Statischer Dateiserver | Liefert Dateien aus deinem Verzeichnis ui/ aus (SPA-Fallback auf index.html) |
ANY /api/v1/apps/{id}/api/* | gRPC-Proxy | Leitet 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 Triggersist 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:
| Datei | Max. Größe | Beschreibung |
|---|---|---|
manifest.json | 1 MB | App-Metadaten |
binary oder app | 500 MB | Ausführbare Datei |
signatures.json | 1 MB | Ed25519-Signaturen |
TOOL.md | 1 MB | Tool-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
- Registriere ein NeboAI-Konto unter
POST /api/v1/owners/register - Melde dich an, um ein JWT-Token zu erhalten:
POST /api/v1/owners/login - 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
- Automatischer Scan — Binärdateien werden mit VirusTotal gescannt
- Prüfung durch Admins — das NeboAI-Team prüft Metadaten, Manifest und Scan-Ergebnisse
- Bei Freigabe — NeboAI signiert die App mit Ed25519 und veröffentlicht sie
- Bei Ablehnung — du erhältst eine Begründung und kannst nachbessern und erneut einreichen
Angestrebte Prüfdauer: <24 Stunden.
Updates veröffentlichen
- Aktualisiere die Version der App:
PUT /api/v1/developer/apps/{id}mit der neuen Version - Lade für jede Plattform neue Binärdateien hoch
- 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
| Feld | Beschreibung |
|---|---|
category | z. B. productivity, communication, developer-tools |
icon | URL des App-Icons |
visibility | public oder private |
description | Darf 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:
- Erstelle dein App-Verzeichnis:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Schreibe deine
manifest.jsonund deinen Code - Baue deine Binärdatei:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo erkennt das neue Verzeichnis automatisch (oder starte Nebo neu)
- 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.lognach 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_SOCKlauschst - Der Socket muss innerhalb von 10 Sekunden nach dem Start bereit sein
- Nutze
NEBO_APP_DATAfü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
| Skills | Apps | |
|---|---|---|
| Format | Markdown (SKILL.md) | Kompilierte Binärdatei (.napp) |
| Laufzeit | In den System-Prompt eingefügt | Prozess in der Sandbox über gRPC |
| Liefert | Verhaltensanleitung, Vorgehensweise | Tools, Kanäle, UI-Panels |
| Lebensdauer | Auf die Sitzung begrenzt, Ablauf per TTL | Läuft ständig |
| Erstellung | Eine Markdown-Datei schreiben | Schreiben, kompilieren, signieren, paketieren |
| Sicherheit | Keine Berechtigungen nötig | Sandbox 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).
| Feld | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
name | Ja | — | Eindeutige Kennung (wird zum Slug) |
description | Ja | — | Einzeilige Beschreibung, die im Skill-Katalog angezeigt wird |
version | Nein | "1.0.0" | Semver zum Nachverfolgen von Updates |
author | Nein | — | Autor des Skills |
priority | Nein | 0 | Höher = wird zuerst abgeglichen (100+ für kritische Überschreibungen) |
max_turns | Nein | 4 | Runden ohne Aktivität bis zum automatischen Ablauf |
triggers | Nein | [] | Formulierungen, die diesen Skill automatisch aktivieren (Teilstring-Abgleich ohne Beachtung der Groß-/Kleinschreibung) |
tools | Nein | [] | Tools, die dieser Skill voraussichtlich nutzt (zur Information) |
dependencies | Nein | [] | Andere Skills, die installiert sein müssen |
tags | Nein | [] | Zur Kategorisierung und Auffindbarkeit |
platform | Nein | [] | 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:
| Aktion | Beschreibung | Beispiel |
|---|---|---|
catalog | Alle verfügbaren Skills auflisten | skill(action: "catalog") |
load | Für diese Sitzung aktivieren | skill(name: "code-review", action: "load") |
unload | Einen Skill deaktivieren | skill(name: "code-review", action: "unload") |
create | Einen neuen Skill auf der Festplatte anlegen | skill(action: "create", content: "...") |
update | Einen bestehenden Skill aktualisieren | skill(name: "my-skill", action: "update", content: "...") |
delete | Einen Skill von der Festplatte löschen | skill(name: "my-skill", action: "delete") |
Gute Skills schreiben
Eine gute Skill-Vorlage hat:
- Eine klare Überschrift — sagt dem KI-Mitarbeiter, in welchem Modus er ist
- Kernprinzipien — die nicht verhandelbaren Verhaltensregeln
- Vorgehensweise — ein Schritt-für-Schritt-Ansatz für häufige Situationen
- Beispiele — konkrete Muster von Nutzernachricht zu Antwort
- 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:
| Skill | Priorität | Beschreibung |
|---|---|---|
onboarding | 100 | Begrüßung neuer Nutzer und Erfassung des Profils |
best-friend | 50 | Persönlichkeits-Skill — locker, loyal, ehrliche Worte |
debugging | 25 | Systematische Methode zur Fehlersuche |
api-design | 15 | Best Practices für das Design von REST-APIs |
code-review | 10 | Strukturiertes Code-Review mit Schweregraden |
database-expert | 10 | Datenbankdesign, Abfragen, Optimierung |
git-workflow | 10 | Git-Branching, Commits, PR-Workflows |
security-audit | 10 | Sicherheitsanalyse 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.
| Datei | Dienst | Wichtige RPCs |
|---|---|---|
v0/common.proto | (nur Nachrichten) | 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 |
Jeder Dienst enthält die RPCs HealthCheck und Configure. Das SDK übernimmt beide automatisch.
Proto-Typen für Kanäle
| Nachrichtentyp | Beschreibung |
|---|---|
ChannelSendRequest | Umschlag für ausgehende Nachrichten mit message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | Nachrichten-ID der Plattform für Threads |
InboundMessage | Umschlag für eingehende Nachrichten mit allen gemeinsamen Feldern + Zeitstempel |
MessageSender | Bot-Identität (name, role, botId) — vom Broker angereichert |
Attachment | Anhang mit Datei/Bild/Audio (type, url, filename, size) |
MessageAction | Interaktive 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“.