NeboAI
NeboAI
Mulai

Bangun Aplikasi untuk Nebo

Beri AI Anda kekuatan super baru. Alat, kanal, gateway, panel UI — apa pun yang bisa Anda bayangkan, dikompilasi menjadi biner native.

Ikhtisar

Apa Itu Nebo

Nebo adalah asisten AI desktop pribadi — karyawan AI yang selalu berjalan dan mengelola kehidupan digital Anda. Anggap Nebo seperti Anda memandang smartphone: platform andal yang menjadi transformatif berkat aplikasinya.

Dengan sendirinya, Nebo adalah karyawan AI yang cakap dengan memori, penjadwalan, penjelajahan web, pengelolaan file, dan akses shell. Namun kunci sebenarnya adalah Aplikasi. Seperti kekuatan smartphone berasal dari ekosistem aplikasinya, kekuatan Nebo berasal dari aplikasi yang memperluas apa yang bisa dilakukannya.

Apa Itu Aplikasi

Aplikasi Nebo adalah unit fungsionalitas luar biasa yang berdiri sendiri dan sudah dikompilasi. Setiap aplikasi memberi Nebo kekuatan super baru — pengelolaan kalender, pemilahan email, pelacakan proyek, otomatisasi rumah, analisis keuangan — apa pun yang bisa dibayangkan developer.

Aplikasi memberikan kekuatan luar biasa dengan cara yang sangat aman. Setiap aplikasi berjalan di sandbox dengan izin yang ditolak secara default. Aplikasi hanya dapat mengakses apa yang dideklarasikan manifesnya dan disetujui pengguna.

Antarmukanya 100% berbasis percakapan. Pengguna tidak berinteraksi dengan aplikasi melalui layar atau dasbor terpisah. Mereka berbicara dengan Nebo, dan Nebo menggunakan alat aplikasi untuk menyelesaikan pekerjaan. "Apa jadwal saya besok?" — Nebo memanggil aplikasi kalender. "Buat rapat dengan Sarah pukul 3 sore" — Nebo memanggil aplikasi kalender. Pengguna tidak pernah meninggalkan percakapan.

Aplikasi secara opsional dapat menyediakan UI pengaturan — panel konfigurasi yang terbuka di jendela browser bawaan Nebo. Di sinilah pengguna memasukkan kunci API, mengaktifkan fitur, dan mengonfigurasi aplikasi. UI pengaturan dikendalikan oleh array settings di manifes (Nebo merender formulirnya secara otomatis), atau aplikasi dapat menyediakan UI kustomnya sendiri sepenuhnya melalui kapabilitas ui.

Aplikasi menggantikan dan memperluas kemampuan bawaan Nebo. Nebo dilengkapi alat platform dasar (akses kalender lokal, tangkapan layar, dll.). Saat Anda memasang aplikasi kalender, aplikasi itu menggantikan alat kalender bawaan dan menjadi superset-nya — lokal + cloud + agregasi + pengecekan ketersediaan.

Kebijakan Hanya Kompilasi

Nebo menerapkan kebijakan ketat yang hanya menerima biner terkompilasi. Semua aplikasi harus berupa executable native yang dikompilasi.

StatusBahasa
DidukungGo (direkomendasikan), Rust, C/C++, Zig
DitolakPython, Node.js, Ruby, Java, .NET, skrip shell

Alasan:

  • Mencegah AI memodifikasi dirinya sendiri — Karyawan AI dengan akses shell dapat mengubah perilaku skrip yang diinterpretasikan saat runtime. Biner terkompilasi tidak dapat diubah setelah ditandatangani.
  • Integritas tanda tangan — Tanda tangan Ed25519 mencakup byte biner mentah. Biner yang ditandatangani tidak dapat dimodifikasi tanpa membatalkan tanda tangannya.
  • Penegakan sandbox — Validasi format biner (magic bytes ELF/Mach-O/PE) adalah gerbang yang cepat dan andal.

Mulai Cepat

Pasang SDK

SDK resmi menangani semua penyiapan server gRPC, penanganan sinyal, dan penjembatanan protokol. Anda cukup mengimplementasikan antarmuka handler.

Go (direkomendasikan):

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

Rust (segera hadir):

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

C/C++ (segera hadir):

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

Struktur Direktori Aplikasi

Aplikasi berada di subdirektori apps/ dari direktori data Nebo Anda:

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

Daftar Periksa Aplikasi Minimal

  1. Buat manifest.json dengan id, name, version, provides
  2. Tulis TOOL.md yang menjelaskan cara karyawan AI menggunakan alat Anda
  3. Pasang SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Implementasikan antarmuka handler untuk kapabilitas Anda (ToolHandler, ChannelHandler, dll.)
  5. Daftarkan handler dan panggil app.Run()
  6. Build biner native (go build -o binary .)
  7. Letakkan biner + manifest.json + TOOL.md di direktori apps/<your-app-id>/
  8. Nebo menemukan dan meluncurkannya secara otomatis

Konfigurasi

manifest.json

Setiap aplikasi memerlukan 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
        }
    ]
}

Field wajib:

FieldDeskripsi
idPengenal domain terbalik (misalnya, com.mycompany.myapp)
nameNama yang mudah dibaca
versionString semver
providesSetidaknya satu kapabilitas (lihat di bawah)

Field opsional:

FieldDefaultDeskripsi
runtime"local""local" atau "remote"
protocol"grpc"Hanya "grpc" yang didukung
permissions[]Apa yang perlu diakses aplikasi
description""Ditampilkan di UI
settings[]Pengaturan yang dapat dikonfigurasi (dirender di UI Pengaturan)
oauth[]Persyaratan penyedia OAuth (lihat bagian OAuth di bawah)

Kapabilitas

Deklarasikan apa yang disediakan aplikasi Anda:

KapabilitasLayanan gRPCDeskripsi
gatewayGatewayServicePerutean model LLM
tool:<name>ToolServiceAlat bernama untuk karyawan AI
channel:<name>ChannelServiceKanal perpesanan
commCommServiceKomunikasi antar-karyawan AI
uiUIServiceUI kustom dengan proxy HTTP
scheduleScheduleServicePenjadwalan kustom
visionToolServicePemrosesan visual
browserToolServiceOtomatisasi browser

Satu aplikasi dapat menyediakan beberapa kapabilitas. Misalnya, sebuah aplikasi dapat menyediakan alat sekaligus panel UI.

Izin

Izin mengatur apa yang dapat diakses aplikasi. Ditolak secara default — jika tidak dideklarasikan, aplikasi tidak dapat menggunakannya.

PrefiksContohDeskripsi
network:network:outbound, network:*Akses jaringan
filesystem:filesystem:read, filesystem:writeAkses sistem file
memory:memory:read, memory:writeAkses memori karyawan AI
session:session:readSesi percakapan
tool:tool:shell, tool:fileMenggunakan alat lain
shell:shell:execEksekusi perintah shell
channel:channel:send, channel:*Operasi kanal
comm:comm:send, comm:*Komunikasi antar-karyawan AI
model:model:chatAkses model AI
user:user:tokenMenerima JWT pengguna dalam permintaan
schedule:schedule:createPengelolaan cron job
database:database:queryAkses database
storage:storage:read, storage:writePenyimpanan persisten
context:context:readAkses konteks karyawan AI
subagent:subagent:spawnOperasi sub-agent
lane:lane:enqueueOperasi lane
notification:notification:sendNotifikasi push
embedding:embedding:searchAkses embedding vektor
skill:skill:invokePemanggilan skill
advisor:advisor:consultAkses sistem penasihat
mcp:mcp:connectAkses server MCP
voice:voice:recordAkses suara/audio
browser:browser:navigateOtomatisasi browser
oauth:oauth:google, oauth:*Akses token OAuth
settings:settings:readAkses pengaturan
capability:capability:registerPendaftaran kapabilitas

Izin wildcard didukung: network:* cocok dengan pemeriksaan izin network: apa pun.

Pengaturan

Pengaturan muncul di UI Nebo pada panel pengaturan aplikasi. Nebo menyimpannya di database dan mengirimkannya ke aplikasi Anda melalui RPC Configure saat berubah.

Skema pengaturan Anda disertakan dalam listing toko aplikasi NeboAI. Aplikasi dengan pengaturan wajib yang belum dikonfigurasi menampilkan lencana "Perlu Penyiapan" di UI.

TipeDeskripsi
textInput teks satu baris
passwordInput teks tersamar
toggleSakelar boolean aktif/nonaktif
selectDropdown dengan opsi yang telah ditentukan
numberInput numerik
urlInput URL dengan validasi
{
    "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"}
    ]
}

Persyaratan OAuth

Aplikasi dapat mendeklarasikan persyaratan penyedia OAuth. Broker OAuth Nebo menangani seluruh alurnya — aplikasi menerima token secara otomatis melalui RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
FieldDeskripsi
providerPenyedia OAuth: "google", "microsoft", "github"
scopesArray cakupan OAuth yang dibutuhkan aplikasi

Saat pengguna memasang aplikasi, Nebo meminta mereka mengotorisasi cakupan OAuth yang diperlukan. Aplikasi menerima token yang diperbarui melalui RPC Configure tanpa menangani alur OAuth sendiri.

Variabel Lingkungan

Proses aplikasi Anda menerima lingkungan yang telah disanitasi. Semua rahasia dihapus. Anda mendapatkan:

VariabelNilai
NEBO_APP_DIRDirektori instalasi aplikasi
NEBO_APP_SOCKPath ke socket Unix yang harus dibuat
NEBO_APP_IDID aplikasi dari manifes
NEBO_APP_NAMENama aplikasi dari manifes
NEBO_APP_VERSIONVersi aplikasi dari manifes
NEBO_APP_DATAPath ke direktori data/ aplikasi
PATHPATH sistem (diteruskan)
HOMEDirektori home pengguna (diteruskan)
TMPDIRDirektori sementara (diteruskan)

Penting: Biner Anda harus membuat server gRPC yang mendengarkan socket Unix di NEBO_APP_SOCK. Nebo menunggu hingga 10 detik sampai socket ini muncul.

Urutan Peluncuran Aplikasi

  1. Nebo membaca manifest.json dan memvalidasinya
  2. Menemukan executable binary atau app di direktori aplikasi
  3. Memeriksa penanda .quarantined (menolak meluncurkan aplikasi yang dikarantina)
  4. Pemeriksaan pencabutan (hanya aplikasi yang didistribusikan NeboAI)
  5. Verifikasi tanda tangan (hanya aplikasi yang didistribusikan NeboAI, dilewati dalam mode dev)
  6. Validasi biner (menolak symlink, skrip, file non-executable, file berukuran terlalu besar)
  7. Membersihkan socket usang dari proses sebelumnya
  8. Membuat direktori data/ untuk penyimpanan dalam sandbox
  9. Menyiapkan file log per aplikasi (logs/stdout.log, logs/stderr.log)
  10. Memulai biner dengan lingkungan yang disanitasi dan isolasi grup proses
  11. Menunggu socket Unix muncul (exponential backoff, maksimal 10 detik)
  12. Terhubung melalui gRPC lewat socket Unix
  13. Membuat klien gRPC khusus kapabilitas berdasarkan provides
  14. Menjalankan pemeriksaan kesehatan
  15. Mendaftarkan kapabilitas ke karyawan AI (alat, gateway, comm, dll.)

Aplikasi Alat

Deklarasikan "provides": ["tool:my_tool_name"] di manifes Anda.

Pola STRAP

Semua aplikasi alat Nebo wajib menggunakan STRAP (Single Tool Resource Action Pattern) untuk skema dan perutean eksekusinya. Ini adalah pola yang sama yang digunakan Nebo secara internal untuk menggabungkan 35+ alat individual menjadi 4 alat domain — mengurangi beban konteks LLM sekitar 80%.

Gagasan inti: Alih-alih mendaftarkan banyak alat (get_events, check_availability, suggest_slots), daftarkan SATU alat dengan field action (dan opsional resource) yang merutekan ke handler yang tepat.

Contoh satu resource (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")

Contoh multi-resource (manajer proyek):

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

Aturan skema:

  1. Selalu sertakan field action sebagai enum string wajib
  2. Tambahkan field resource (enum string wajib) hanya jika alat Anda mengelola beberapa tipe resource yang berbeda
  3. Semua field lainnya adalah parameter khusus action
  4. Deskripsi enum action harus mencantumkan semua action yang tersedia

Mengapa STRAP penting:

  • LLM mempelajari pola perutean action sekali dan menerapkannya ke semua operasi
  • Definisi alat memakan ~6% konteks — STRAP memangkasnya hingga 80%
  • Operasi baru cukup berupa penambahan enum, bukan pendaftaran alat baru
  • Bekerja secara identik di model yang di-host maupun model lokal

Contoh Go — Alat Kalkulator

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

Build dan pasang:

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/

Contoh Rust

use async_trait::async_trait;
use nebo_sdk::{NeboApp, NeboError, SchemaBuilder};
use nebo_sdk::tool::ToolHandler;
use serde::Deserialize;
use serde_json::Value;

struct Calculator;

#[derive(Deserialize)]
struct Input { action: String, a: f64, b: f64 }

#[async_trait]
impl ToolHandler for Calculator {
    fn name(&self) -> &str { "calculator" }
    fn description(&self) -> &str { "Performs arithmetic calculations." }
    fn schema(&self) -> Value {
        SchemaBuilder::new(&["add", "subtract", "multiply", "divide"])
            .number("a", "First operand", true)
            .number("b", "Second operand", true)
            .build()
    }
    async fn execute(&self, input: Value) -> Result<String, NeboError> {
        let i: Input = serde_json::from_value(input)
            .map_err(|e| NeboError::Execution(e.to_string()))?;
        let r = match i.action.as_str() {
            "add" => i.a + i.b,
            "subtract" => i.a - i.b,
            "multiply" => i.a * i.b,
            "divide" => {
                if i.b == 0.0 {
                    return Err(NeboError::Execution("division by zero".into()));
                }
                i.a / i.b
            }
            other => return Err(NeboError::Execution(format!("unknown action: {other}"))),
        };
        Ok(format!("{} {} {} = {}", i.a, i.action, i.b, r))
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    NeboApp::new()?.register_tool(Calculator).run().await?;
    Ok(())
}

Contoh C

#include <nebo/nebo.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static int calculator_execute(const char *input_json, char **output, int *is_error) {
    /* Parse JSON, compute result, set *output */
    *output = strdup("2 add 3 = 5");
    *is_error = 0;
    return 0;
}

int main(void) {
    const char *actions[] = {"add", "subtract", "multiply", "divide", NULL};
    nebo_schema_builder_t *sb = nebo_schema_new(actions);
    nebo_schema_number(sb, "a", "First operand", 1);
    nebo_schema_number(sb, "b", "Second operand", 1);
    char *schema = nebo_schema_build(sb);
    nebo_schema_free(sb);

    nebo_tool_handler_t calculator = {
        .name = "calculator",
        .description = "Performs arithmetic calculations.",
        .schema = schema,
        .execute = calculator_execute,
    };

    nebo_app_t *app = nebo_app_new();
    nebo_app_register_tool(app, &calculator);
    int ret = nebo_app_run(app);
    free(schema);
    return ret;
}

Aplikasi Kanal

Deklarasikan "provides": ["channel:my_channel"] dan "permissions": ["channel:send"].

Aplikasi kanal menjembatani platform perpesanan eksternal (Telegram, Discord, Slack, dll.) ke karyawan AI Nebo. Saat pengguna mengirim pesan di platform eksternal, aplikasi Anda mengalirkannya ke Nebo melalui Receive. Saat karyawan AI ingin membalas, Nebo memanggil Send milik aplikasi Anda.

Cara kerjanya

  1. Nebo memanggil ID() untuk mendapatkan pengenal unik kanal Anda
  2. Nebo memanggil Connect() dengan konfigurasi dari pengaturan aplikasi Anda
  3. Nebo membuka stream Receive() — aplikasi Anda mengirim pesan masuk setiap kali pengguna mengirim pesan ke bot
  4. Pesan masuk dirutekan ke lane percakapan utama karyawan AI
  5. Saat karyawan AI ingin mengirim pesan, Nebo memanggil Send() dengan amplop pesan v1
  6. Saat dimatikan, Nebo memanggil Disconnect()

Amplop Pesan v1

Semua pesan kanal — masuk maupun keluar — menggunakan amplop pesan bersama:

{
  "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"
}
FieldTipeDeskripsi
message_idUUID v7ID unik berurutan waktu
channel_id{type}:{platform_id}Pengenal kanal yang dapat dirutekan
senderobjectIdentitas bot — name, role, botId
textstringIsi pesan
attachmentsarrayFile, gambar, audio
reply_toUUID v7ID pesan induk untuk utas
actionsarrayTombol/keyboard interaktif
platform_databytesData passthrough buram untuk fitur khusus platform
timestampISO 8601Diisi oleh penerbit

Desain dua lapis: Field umum (text, attachments, reply_to, actions) mencakup 90% pesan yang dimulai oleh karyawan. Fitur khusus platform masuk ke platform_data — plugin Anda memetakannya ke dan dari format native platform.

Stream Percakapan

Pesan kanal dirutekan melalui stream percakapan per kanal untuk isolasi:

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

Contoh Go — Kanal Telegram

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "time"

    "github.com/google/uuid"
    tgbot "github.com/go-telegram/bot"
    nebo "github.com/neboloop/nebo-sdk-go"
)

type Telegram struct {
    bot      *tgbot.Bot
    messages chan nebo.ChannelEnvelope
    cancel   context.CancelFunc
}

func (t *Telegram) ID() string { return "telegram" }

func (t *Telegram) Connect(_ context.Context, config map[string]string) error {
    token := config["bot_token"]
    if token == "" {
        return fmt.Errorf("bot_token is required")
    }

    botCtx, cancel := context.WithCancel(context.Background())
    t.cancel = cancel

    bot, err := tgbot.New(token, tgbot.WithDefaultHandler(
        func(bCtx context.Context, b *tgbot.Bot, update *tgbot.Update) {
            if update.Message == nil {
                return
            }
            env := nebo.ChannelEnvelope{
                MessageID: uuid.Must(uuid.NewV7()).String(),
                ChannelID: fmt.Sprintf("telegram:%d", update.Message.Chat.ID),
                Text:      update.Message.Text,
                Timestamp: time.Unix(int64(update.Message.Date), 0).UTC(),
            }
            t.messages <- env
        },
    ))
    if err != nil {
        return err
    }

    t.bot = bot
    go bot.Start(botCtx)
    return nil
}

func (t *Telegram) Send(ctx context.Context, env nebo.ChannelEnvelope) (string, error) {
    if t.bot == nil {
        return "", fmt.Errorf("not connected")
    }
    chatID := env.ChannelID[len("telegram:"):]
    params := &tgbot.SendMessageParams{
        ChatID: chatID,
        Text:   env.Text,
    }
    msg, err := t.bot.SendMessage(ctx, params)
    if err != nil {
        return "", err
    }
    return fmt.Sprintf("%d", msg.MessageID), nil
}

func (t *Telegram) Receive(_ context.Context) (<-chan nebo.ChannelEnvelope, error) {
    return t.messages, nil
}

func (t *Telegram) Disconnect(_ context.Context) error {
    if t.cancel != nil {
        t.cancel()
    }
    return nil
}

func main() {
    app, err := nebo.New()
    if err != nil {
        log.Fatal(err)
    }
    app.RegisterChannel(&Telegram{
        messages: make(chan nebo.ChannelEnvelope, 100),
    })
    log.Fatal(app.Run())
}

manifest.json:

{
    "id": "com.example.telegram",
    "name": "Telegram",
    "version": "1.0.0",
    "description": "Telegram messaging channel for Nebo",
    "runtime": "local",
    "protocol": "grpc",
    "provides": ["channel:telegram"],
    "permissions": ["channel:send", "network:outbound"],
    "settings": [
        {
            "key": "bot_token",
            "title": "Bot Token",
            "type": "password",
            "required": true,
            "description": "Telegram bot token from @BotFather",
            "secret": true
        }
    ]
}

Kapabilitas Lainnya

Aplikasi Comm

Deklarasikan "provides": ["comm"] dan "permissions": ["comm:*"]. Aplikasi comm memungkinkan komunikasi antar-karyawan AI.

FieldDeskripsi
fromID karyawan pengirim
toID karyawan penerima
topicTopik/kanal pesan
type"message", "mention", "proposal", "command", "info", "task"
contentIsi pesan

Perilaku utama:

  • Register mengumumkan karyawan AI ini di jaringan beserta kapabilitasnya
  • Subscribe/Unsubscribe mengelola langganan topik
  • Receive mengalirkan pesan masuk (server-streaming, sama seperti kanal)
  • Hanya satu aplikasi comm yang dapat aktif pada satu waktu

Aplikasi Gateway

Aplikasi gateway merutekan permintaan LLM ke model. Deklarasikan "provides": ["gateway"] dan "permissions": ["network:outbound", "user:token"].

GatewayRequest berisi pesan, alat, system prompt, max tokens, temperature, dan UserContext (token JWT jika izin user:token diberikan).

Tipe GatewayEvent:

TipeKontenDeskripsi
"text"Potongan teksToken teks streaming
"tool_call"JSONModel ingin memanggil alat
"thinking"Potongan teksExtended thinking/penalaran
"error"Pesan errorTerjadi kesalahan
"done"KosongStream selesai

Aplikasi UI

Aplikasi UI menyediakan antarmuka konfigurasi kustom yang terbuka di jendela browser bawaan Nebo. Deklarasikan "provides": ["ui"]. Berbeda dengan formulir pengaturan otomatis (yang dirender Nebo dari manifes settings Anda), aplikasi UI menyajikan frontend HTML/CSS/JS lengkapnya sendiri.

Aplikasi Anda menyertakan direktori ui/ yang berisi aset web statis (HTML, CSS, JS — biasanya SPA dengan index.html). Nebo menyajikan file-file ini secara langsung dan mem-proxy panggilan API ke aplikasi Anda melalui gRPC.

PathMekanismeTujuan
GET /api/v1/apps/{id}/ui/*Server file statisMenyajikan file dari direktori ui/ Anda (fallback SPA ke index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCMem-proxy permintaan HTTP ke UIService.HandleRequest() milik aplikasi Anda

SDK membungkus net/http.ServeMux standar sehingga Anda menulis handler HTTP Go biasa — SDK menangani penjembatanan gRPC secara otomatis.

Contoh Go — UI Dasbor:

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

ui/index.html Anda akan melakukan panggilan fetch ke /api/v1/apps/com.example.dashboard/api/status, yang di-proxy ke handler mux Anda.

Aplikasi Jadwal

Aplikasi jadwal menggantikan penjadwal cron bawaan Nebo. Deklarasikan "provides": ["schedule"] dan "permissions": ["schedule:create"].

Saat aplikasi jadwal Anda diluncurkan, Nebo merutekan semua penjadwalan melalui aplikasi Anda, bukan mesin cron default. Jika aplikasi Anda crash, Nebo otomatis kembali ke mesin bawaan.

  • Aplikasi Anda memegang status jadwal — Nebo tidak menyimpan jadwal di DB-nya sendiri saat aplikasi jadwal aktif
  • CRUD standar: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers adalah RPC server-streaming — aplikasi Anda mengirim pesan pemicu setiap kali jadwal berjalan
  • Hanya satu aplikasi jadwal yang dapat aktif pada satu waktu

Aplikasi Multi-Kapabilitas

Satu aplikasi dapat menyediakan beberapa kapabilitas. Misalnya, aplikasi dasbor dengan alat sekaligus 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())

Pengemasan

Format .napp

Untuk distribusi melalui NeboAI, kemas aplikasi Anda sebagai file .napp (arsip tar.gz):

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

File wajib:

FileUkuran MaksDeskripsi
manifest.json1 MBMetadata aplikasi
binary atau app500 MBExecutable
signatures.json1 MBTanda tangan Ed25519
TOOL.md1 MBInstruksi alat untuk karyawan AI

Aturan keamanan saat ekstraksi:

  • Tanpa path traversal (../ ditolak)
  • Tanpa symlink (ditolak)
  • Tanpa path absolut (ditolak)
  • Hanya nama file dalam daftar yang diizinkan yang diterima

Tanda Tangan

NeboAI menandatangani aplikasi dengan Ed25519. Format 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>"
}

Dalam mode dev (tanpa URL NeboAI yang dikonfigurasi), verifikasi tanda tangan dilewati sepenuhnya. Anda tidak memerlukan signatures.json untuk pengembangan lokal.

Publikasi

Setelah aplikasi Anda berfungsi secara lokal, publikasikan melalui NeboAI untuk didistribusikan ke semua pengguna Nebo.

Penyiapan Akun Developer

  1. Daftarkan akun NeboAI di POST /api/v1/owners/register
  2. Masuk untuk mendapatkan token JWT: POST /api/v1/owners/login
  3. Buat akun developer: POST /api/v1/developer/accounts

Alur Pengiriman

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

Langkah 1: Buat aplikasi

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

Langkah 2: Unggah biner 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"

Unggah satu biner per platform: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Langkah 3: Kirim untuk ditinjau

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

Proses Peninjauan

  1. Pemindaian otomatis — biner dipindai melalui VirusTotal
  2. Peninjauan admin — tim NeboAI meninjau metadata, manifes, dan hasil pemindaian
  3. Jika disetujui — NeboAI menandatangani aplikasi dengan Ed25519 dan memublikasikannya
  4. Jika ditolak — Anda menerima alasannya dan dapat memperbaiki lalu mengirim ulang

Target waktu peninjauan: <24 jam.

Mengirim Pembaruan

  1. Perbarui versi aplikasi: PUT /api/v1/developer/apps/{id} dengan versi baru
  2. Unggah biner baru untuk setiap platform
  3. Kirim untuk ditinjau lagi

Setiap pembaruan melalui proses peninjauan yang sama. Versi sebelumnya tetap tersedia hingga versi baru disetujui.

Metadata Toko

FieldDeskripsi
categorymisalnya, productivity, communication, developer-tools
iconURL ikon aplikasi
visibilitypublic atau private
descriptionBisa lebih panjang/lebih kaya daripada deskripsi manifes

Workflow Dev

Pengembangan Lokal

Tidak perlu pengemasan untuk pengembangan lokal:

  1. Buat direktori aplikasi Anda:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Tulis manifest.json dan kode Anda
  3. Build binary Anda:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo mendeteksi direktori baru secara otomatis (atau mulai ulang Nebo)
  5. Setelah kode diubah, build ulang binernya — file watcher akan memulai ulang aplikasi

Melihat Log

stdout/stderr aplikasi direkam dalam file log per aplikasi:

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

Data Persisten

Gunakan direktori data/ (juga tersedia sebagai variabel lingkungan NEBO_APP_DATA) untuk file apa pun yang perlu disimpan aplikasi Anda secara persisten. Direktori ini tetap ada setelah pembaruan aplikasi dan karantina.

Tips Debugging

  • Jika aplikasi Anda tidak mau mulai, periksa logs/stderr.log untuk melihat error
  • Pastikan binernya dapat dieksekusi (chmod +x binary)
  • Pastikan Anda mendengarkan path socket Unix dari NEBO_APP_SOCK
  • Socket harus siap dalam 10 detik setelah peluncuran
  • Gunakan NEBO_APP_DATA untuk penyimpanan, bukan path yang di-hardcode
  • Cetak ke stderr untuk log debug (direkam di logs/stderr.log)

Memverifikasi

# 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

Mencopot pemasangan

nebo apps uninstall com.example.myapp

Skill

Apa Itu Skill

Skill adalah kumpulan instruksi yang membentuk cara Nebo berperilaku selama percakapan. Saat skill aktif, isinya disuntikkan langsung ke system prompt — memandu nada, metodologi, keahlian domain, dan penggunaan alat karyawan AI untuk sesi tersebut.

Skill bukan kode. Skill adalah dokumen markdown dengan metadata YAML. Tanpa kompilasi, tanpa biner, tanpa gRPC. Skill adalah file SKILL.md di sebuah direktori. Itu saja.

Skill bersifat kontekstual dan sementara. Skill aktif saat relevan (melalui pencocokan pemicu atau dimuat manual), bertahan selama beberapa giliran, dan kedaluwarsa saat tidak lagi dibutuhkan. Ini menjaga konteks karyawan AI tetap ramping — hanya panduan yang penting saat ini yang ada di prompt.

Skill melengkapi aplikasi. Aplikasi menyediakan kapabilitas yang dapat dieksekusi (alat, kanal, gateway). Skill menyediakan panduan orkestrasi — cara menggunakan alat-alat itu secara efektif. Aplikasi kalender memberi Nebo kemampuan membaca dan menulis event. Skill "persiapan rapat" memberi tahu Nebo cara mempersiapkan rapat dengan menggunakan aplikasi kalender, email, dan pencarian web bersama-sama.

Skill vs Aplikasi

SkillAplikasi
FormatMarkdown (SKILL.md)Biner terkompilasi (.napp)
RuntimeDisuntikkan ke system promptProses dalam sandbox melalui gRPC
MenyediakanPanduan perilaku, metodologiAlat, kanal, panel UI
Masa aktifTerbatas pada sesi, kedaluwarsa berbasis TTLSelalu berjalan
PembuatanTulis file markdownTulis, kompilasi, tanda tangani, kemas
KeamananTidak perlu izinSandbox yang menolak secara default

Mulai Cepat

Buat direktori di folder skill Nebo Anda dengan file SKILL.md:

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

Tulis 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 memantau direktori skill dengan fsnotify. Skill Anda langsung tersedia — tidak perlu memulai ulang. Ucapkan sesuatu yang cocok dengan pemicu, dan skill aktif secara otomatis.

Atau minta langsung kepada Nebo: "Buat skill untuk menulis postingan blog" — Nebo akan menulis file SKILL.md untuk Anda.

Format SKILL.md

Setiap skill adalah satu file SKILL.md dengan dua bagian: frontmatter YAML di antara penanda ---, dan isi markdown (instruksi sebenarnya yang disuntikkan ke system prompt).

FieldWajibDefaultDeskripsi
nameYa—Pengenal unik (menjadi slug)
descriptionYa—Deskripsi satu baris yang ditampilkan di katalog skill
versionTidak"1.0.0"Semver untuk melacak pembaruan
authorTidak—Penulis skill
priorityTidak0Lebih tinggi = dicocokkan lebih dulu (100+ untuk penimpaan kritis)
max_turnsTidak4Jumlah giliran tanpa aktivitas sebelum kedaluwarsa otomatis
triggersTidak[]Frasa yang mengaktifkan skill ini secara otomatis (pencocokan substring, tidak peka huruf besar/kecil)
toolsTidak[]Alat yang akan digunakan skill ini (informatif)
dependenciesTidak[]Skill lain yang harus dipasang
tagsTidak[]Untuk kategorisasi dan penemuan
platformTidak[]Platform yang didukung: macos, linux, windows (kosong = semua)

Cara Skill Aktif

Skill mengikuti model aktivasi dua fase: petunjuk lalu pemanggilan.

Fase 1: Pencocokan Pemicu — Setiap kali pengguna mengirim pesan, Nebo memindai semua skill terdaftar untuk mencari kecocokan pemicu. Skill yang cocok muncul sebagai petunjuk di system prompt. Karyawan AI melihat petunjuk itu dan memutuskan apakah akan memanggil skill tersebut.

Fase 2: Pemanggilan — Karyawan AI memanggil skill dengan memanggil:

skill(name: "code-review")

Ini mengembalikan templat SKILL.md lengkap sebagai hasil alat, mencatat pemanggilan, dan menyuntikkan kembali templat ke system prompt pada giliran berikutnya.

TTL dan Kedaluwarsa:

  • Skill yang dicocokkan otomatis: 4 giliran tanpa aktivitas (dapat dikonfigurasi melalui max_turns)
  • Skill yang dimuat manual: 6 giliran tanpa aktivitas
  • Pemanggilan ulang mengatur ulang timer
  • Batas keras: maksimal 4 skill aktif per sesi
  • Anggaran token: total konten skill aktif dibatasi 16,000 karakter

Mengelola Skill

Karyawan AI dapat mengelola skill melalui alat skill:

ActionDeskripsiContoh
catalogDaftar semua skill yang tersediaskill(action: "catalog")
loadAktifkan untuk sesi iniskill(name: "code-review", action: "load")
unloadNonaktifkan skillskill(name: "code-review", action: "unload")
createBuat skill baru di diskskill(action: "create", content: "...")
updatePerbarui skill yang sudah adaskill(name: "my-skill", action: "update", content: "...")
deleteHapus skill dari diskskill(name: "my-skill", action: "delete")

Menulis Skill yang Baik

Templat skill yang baik memiliki:

  1. Judul yang jelas — memberi tahu karyawan AI mode apa yang sedang dijalankannya
  2. Prinsip inti — aturan perilaku yang tidak bisa ditawar
  3. Metodologi — pendekatan langkah demi langkah untuk skenario umum
  4. Contoh — pola konkret dari pesan pengguna ke respons
  5. Anti-pola — apa yang TIDAK boleh dilakukan (model belajar dengan baik dari contoh negatif)

Tips: Setiap skill sebaiknya melakukan satu hal dengan baik. Jangan membuat skill "pemrograman umum" — buat code-review, debugging, api-design sebagai skill terpisah. Karyawan AI dapat mengaktifkan beberapa skill sekaligus.

Skill Bawaan

Nebo dilengkapi skill bawaan yang mencakup kasus penggunaan umum:

SkillPrioritasDeskripsi
onboarding100Sapaan pengguna baru dan pengumpulan profil
best-friend50Skill kepribadian — santai, setia, bicara apa adanya
debugging25Metodologi debugging yang sistematis
api-design15Praktik terbaik desain API RESTful
code-review10Code review terstruktur dengan tingkat keparahan
database-expert10Desain database, kueri, optimasi
git-workflow10Branching Git, commit, workflow PR
security-audit10Analisis keamanan dan deteksi kerentanan

Skill ini berfungsi sebagai default yang berguna sekaligus implementasi referensi untuk membuat skill Anda sendiri.

Referensi

File Proto

File proto berada di proto/apps/v0/. SDK sudah menyertakan kode yang dihasilkan sebelumnya, jadi Anda tidak memerlukan protoc untuk pengembangan normal.

FileLayananRPC Utama
v0/common.proto(hanya pesan)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

Setiap layanan menyertakan RPC HealthCheck dan Configure. SDK menangani keduanya secara otomatis.

Tipe Proto Kanal

Tipe PesanDeskripsi
ChannelSendRequestAmplop pesan keluar dengan message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID pesan platform untuk utas
InboundMessageAmplop pesan masuk dengan semua field umum + timestamp
MessageSenderIdentitas bot (name, role, botId) — dilengkapi oleh broker
AttachmentLampiran file/gambar/audio (type, url, filename, size)
MessageActionAksi tombol/keyboard interaktif (label, callback_id)

Identitas dan Peran Bot

Bot Nebo memiliki model identitas tiga sumbu:

  • creature — Apa bot itu (arketipe): "Ahli strategi yang cerdas", "Peneliti yang teliti"
  • role — Bagaimana hubungannya dengan pengguna (relasi): "Teman", "COO", "Mentor"
  • vibe — Energinya (gaya komunikasi): "Santai tapi punya pendapat", "Hangat dan menyemangati"

Saat plugin kanal Anda menerima pesan keluar, field sender berisi name dan role bot. Gunakan ini untuk memformat nama tampilan di platform Anda. Role bukanlah jabatan — melainkan penanda hubungan. "Teman", "Anak", dan "Mentor" adalah role yang valid di samping "COO" dan "DevLead".