NeboAI
NeboAI
Magsimula

Bumuo ng mga App para sa Nebo

Bigyan ang AI mo ng mga bagong superpower. Mga tool, channel, gateway, UI panel — anumang maiisip mo, naka-compile bilang native binary.

Pangkalahatang-ideya

Ano ang Nebo

Ang Nebo ay isang personal na desktop AI assistant — isang laging tumatakbong AI employee na namamahala sa digital mong buhay. Isipin ang Nebo gaya ng pag-iisip mo sa isang smartphone: isang malakas na platform na nagiging makabago dahil sa mga app nito.

Kahit mag-isa, may kakayahang AI employee na ang Nebo na may memory, pag-iskedyul, pag-browse sa web, pamamahala ng file, at shell access. Pero ang totoong susi ay ang mga App. Kung paanong nagmumula sa app ecosystem ang lakas ng smartphone, nagmumula ang lakas ng Nebo sa mga app na nagpapalawak sa kaya nitong gawin.

Ano ang mga App

Ang mga Nebo App ay mga buo at precompiled na unit ng napakahusay na functionality. Bawat app ay nagbibigay sa Nebo ng bagong superpower — pamamahala ng kalendaryo, pagsala ng email, pagsubaybay ng proyekto, home automation, pagsusuri ng pananalapi — anumang maiisip ng isang developer.

Nagbibigay ang mga app ng napakalaking kakayahan sa napakaligtas na paraan. Tumatakbo ang bawat app sa isang sandbox na deny-by-default ang mga pahintulot. Maa-access lang nito ang idinedeklara ng manifest nito at inaaprubahan ng user.

100% conversational ang interface. Hindi nakikipag-ugnayan ang mga user sa mga app sa pamamagitan ng hiwalay na screen o dashboard. Kinakausap nila ang Nebo, at ginagamit ng Nebo ang mga tool ng app para matapos ang mga bagay. "Ano ang nasa kalendaryo ko bukas?" — tinatawag ng Nebo ang calendar app. "Gumawa ng meeting kasama si Sarah nang 3pm" — tinatawag ng Nebo ang calendar app. Hindi kailanman umaalis ang user sa usapan.

Puwedeng magbigay ang mga app ng opsyonal na settings UI — isang configuration panel na bumubukas sa built-in na browser window ng Nebo. Dito inilalagay ng mga user ang mga API key, nag-o-on/off ng mga feature, at kino-configure ang app. Pinapatakbo ang settings UI ng settings array sa manifest (kusang nire-render ng Nebo ang form), o puwedeng magbigay ang app ng sarili nitong buong custom UI sa pamamagitan ng ui capability.

Pinapalitan at pinapalawak ng mga app ang mga built-in na kakayahan ng Nebo. May kasamang mga basic na platform tool ang Nebo (lokal na access sa kalendaryo, screenshot, atbp.). Kapag nag-install ka ng calendar app, pinapalitan nito ang built-in na calendar tool at nagiging superset — lokal + cloud + aggregation + pagtingin ng availability.

Patakarang Compiled Lang

Mahigpit na ipinapatupad ng Nebo ang patakarang compiled binary lang. Dapat native compiled executable ang lahat ng app.

StatusMga Wika
SuportadoGo (inirerekomenda), Rust, C/C++, Zig
TinatanggihanPython, Node.js, Ruby, Java, .NET, shell script

Dahilan:

  • Pag-iwas sa pagbabago ng AI sa sarili nito — Ang AI employee na may shell access ay puwedeng magbago sa kilos ng isang interpreted script habang tumatakbo ito. Hindi na nababago ang mga compiled binary pagkatapos pirmahan.
  • Integridad ng pirma — Sinasaklaw ng mga Ed25519 signature ang raw na bytes ng binary. Hindi mababago ang isang pinirmahang binary nang hindi nasisira ang pirma.
  • Pagpapatupad ng sandbox — Mabilis at maaasahang harang ang pag-validate ng binary format (ELF/Mach-O/PE magic bytes).

Quick Start

I-install ang SDK

Ang mga opisyal na SDK na ang bahala sa lahat ng setup ng gRPC server, paghawak ng signal, at protocol bridging. Ipapatupad mo lang ang mga handler interface.

Go (inirerekomenda):

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

Rust (malapit na):

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

C/C++ (malapit na):

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

Istruktura ng App Directory

Nasa apps/ na subdirectory ng Nebo data directory mo ang mga app:

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

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

Checklist para sa Minimal na App

  1. Gumawa ng manifest.json na may id, name, version, provides
  2. Isulat ang TOOL.md na naglalarawan kung paano dapat gamitin ng AI employee ang tool mo
  3. I-install ang SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Ipatupad ang handler interface para sa capability mo (ToolHandler, ChannelHandler, atbp.)
  5. I-register ang handler at tawagin ang app.Run()
  6. Mag-build ng native binary (go build -o binary .)
  7. Ilagay ang binary + manifest.json + TOOL.md sa apps/<your-app-id>/ na directory
  8. Kusang natutuklasan at inilulunsad ito ng Nebo

Configuration

manifest.json

Bawat app ay nangangailangan ng 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
        }
    ]
}

Mga kailangang field:

FieldPaglalarawan
idReverse-domain identifier (hal., com.mycompany.myapp)
namePangalang nababasa ng tao
versionSemver string
providesKahit isang capability (tingnan sa ibaba)

Mga opsyonal na field:

FieldDefaultPaglalarawan
runtime"local""local" o "remote"
protocol"grpc""grpc" lang ang suportado
permissions[]Ang kailangang ma-access ng app
description""Ipinapakita sa UI
settings[]Mga setting na puwedeng i-configure (nire-render sa Settings UI)
oauth[]Mga kailangan sa OAuth provider (tingnan ang seksyong OAuth sa ibaba)

Mga Capability

Ideklara kung ano ang ibinibigay ng app mo:

CapabilitygRPC ServicePaglalarawan
gatewayGatewayServicePagruta ng LLM model
tool:<name>ToolServiceIsang may-pangalang tool para sa AI employee
channel:<name>ChannelServiceIsang messaging channel
commCommServiceKomunikasyon sa pagitan ng mga AI employee
uiUIServiceCustom UI na may HTTP proxy
scheduleScheduleServiceCustom na pag-iskedyul
visionToolServicePagproseso ng vision
browserToolServiceBrowser automation

Puwedeng magbigay ang isang app ng maraming capability. Halimbawa, puwedeng magbigay ang isang app ng tool at UI panel.

Mga Pahintulot

Kinokontrol ng mga pahintulot kung ano ang maa-access ng app. Deny by default — kung hindi idineklara, hindi ito magagamit ng app.

PrefixMga HalimbawaPaglalarawan
network:network:outbound, network:*Access sa network
filesystem:filesystem:read, filesystem:writeAccess sa file system
memory:memory:read, memory:writeAccess sa memory ng AI employee
session:session:readMga session ng usapan
tool:tool:shell, tool:filePaggamit ng ibang tool
shell:shell:execPagpapatakbo ng shell command
channel:channel:send, channel:*Mga operasyon sa channel
comm:comm:send, comm:*Komunikasyon sa pagitan ng mga AI employee
model:model:chatAccess sa AI model
user:user:tokenPagtanggap ng user JWT sa mga request
schedule:schedule:createPamamahala ng cron job
database:database:queryAccess sa database
storage:storage:read, storage:writePersistent storage
context:context:readAccess sa context ng AI employee
subagent:subagent:spawnMga operasyon ng sub-agent
lane:lane:enqueueMga operasyon ng lane
notification:notification:sendPush notification
embedding:embedding:searchAccess sa vector embedding
skill:skill:invokePag-invoke ng skill
advisor:advisor:consultAccess sa advisor system
mcp:mcp:connectAccess sa MCP server
voice:voice:recordAccess sa voice/audio
browser:browser:navigateBrowser automation
oauth:oauth:google, oauth:*Access sa OAuth token
settings:settings:readAccess sa settings
capability:capability:registerPag-register ng capability

Suportado ang mga wildcard na pahintulot: tumutugma ang network:* sa anumang pagsusuri ng network: na pahintulot.

Settings

Lumalabas ang settings sa Nebo UI sa ilalim ng settings panel ng app. Iniimbak ng Nebo ang mga ito sa database at ipinapadala sa app mo sa pamamagitan ng Configure RPC kapag nagbago ang mga ito.

Kasama ang settings schema mo sa listing ng NeboAI app store. Ang mga app na may hindi pa naka-configure na kailangang setting ay nagpapakita ng "Needs Setup" na badge sa UI.

UriPaglalarawan
textIsang linyang text input
passwordNakatagong text input
toggleBoolean na on/off switch
selectDropdown na may nakatakdang mga opsyon
numberNumerong input
urlURL input na may validation
{
    "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"}
    ]
}

Mga Kailangan sa OAuth

Puwedeng magdeklara ang mga app ng mga kailangan sa OAuth provider. Ang OAuth broker ng Nebo ang bahala sa buong flow — kusang natatanggap ng mga app ang mga token sa pamamagitan ng Configure RPC.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
FieldPaglalarawan
providerOAuth provider: "google", "microsoft", "github"
scopesArray ng mga OAuth scope na kailangan ng app

Kapag in-install ng user ang app, hinihiling ng Nebo na i-authorize nila ang mga kailangang OAuth scope. Natatanggap ng app ang mga na-refresh na token sa pamamagitan ng Configure RPC nang hindi na nito hinahawakan ang OAuth flow.

Mga Environment Variable

Nakakatanggap ang proseso ng app mo ng nalinis na environment. Inaalis ang lahat ng secret. Ang makukuha mo:

VariableHalaga
NEBO_APP_DIRInstallation directory ng app
NEBO_APP_SOCKPath papunta sa Unix socket na gagawin
NEBO_APP_IDApp ID mula sa manifest
NEBO_APP_NAMEPangalan ng app mula sa manifest
NEBO_APP_VERSIONBersyon ng app mula sa manifest
NEBO_APP_DATAPath papunta sa data/ directory ng app
PATHSystem PATH (passthrough)
HOMEHome directory ng user (passthrough)
TMPDIRTemp directory (passthrough)

Mahalaga: Dapat gumawa ang binary mo ng gRPC server na nakikinig sa Unix socket sa NEBO_APP_SOCK. Naghihintay ang Nebo nang hanggang 10 segundo para lumabas ang socket na ito.

Pagkakasunod-sunod ng Paglulunsad ng App

  1. Binabasa at vina-validate ng Nebo ang manifest.json
  2. Hinahanap ang binary o app na executable sa app directory
  3. Tinitingnan kung may .quarantined na marker (tumatangging ilunsad ang mga naka-quarantine na app)
  4. Pagsusuri ng revocation (para lang sa mga app na ipinamamahagi ng NeboAI)
  5. Pag-verify ng pirma (para lang sa mga app na ipinamamahagi ng NeboAI, nilalaktawan sa dev)
  6. Pag-validate ng binary (tinatanggihan ang mga symlink, script, hindi executable, at sobrang laking file)
  7. Nililinis ang lumang socket mula sa nakaraang run
  8. Gumagawa ng data/ directory para sa naka-sandbox na storage
  9. Nagse-set up ng mga log file bawat app (logs/stdout.log, logs/stderr.log)
  10. Sinisimulan ang binary gamit ang nalinis na environment at paghihiwalay ng process group
  11. Hinihintay na lumabas ang Unix socket (exponential backoff, hanggang 10 segundo)
  12. Kumokonekta sa pamamagitan ng gRPC sa Unix socket
  13. Gumagawa ng mga gRPC client para sa bawat capability batay sa provides
  14. Nagpapatakbo ng health check
  15. Nire-register ang mga capability sa AI employee (mga tool, gateway, comm, atbp.)

Mga Tool App

Ideklara ang "provides": ["tool:my_tool_name"] sa manifest mo.

Ang STRAP Pattern

Lahat ng Nebo tool app ay dapat gumamit ng STRAP (Single Tool Resource Action Pattern) para sa schema at pagruta ng execution nila. Ito rin ang pattern na ginagamit ng Nebo sa loob para pagsamahin ang 35+ na hiwalay na tool sa 4 na domain tool — binabawasan ang LLM context overhead nang ~80%.

Pangunahing ideya: Sa halip na mag-register ng maraming tool (get_events, check_availability, suggest_slots), mag-register ng ISANG tool na may action (at opsyonal na resource) na field na nagruruta sa tamang handler.

Halimbawang iisang resource (kalendaryo):

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

Halimbawang maraming resource (project manager):

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

Mga patakaran sa schema:

  1. Laging magsama ng action na field bilang required na string enum
  2. Magdagdag ng resource na field (required na string enum) kung maraming magkakaibang uri ng resource lang ang pinamamahalaan ng tool mo
  3. Mga parameter na para sa partikular na action ang lahat ng iba pang field
  4. Dapat ilista ng paglalarawan ng action enum ang lahat ng available na action

Bakit mahalaga ang STRAP:

  • Isang beses lang natututunan ng mga LLM ang action routing pattern at nagagamit ito sa lahat ng operasyon
  • Kumokonsumo ng ~6% ng context ang mga tool definition — binabawasan iyon ng STRAP nang 80%
  • Dagdag lang sa enum ang mga bagong operasyon, hindi bagong pag-register ng tool
  • Pareho ang gana sa mga hosted at lokal na model

Halimbawa sa Go — Calculator 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": []
}

I-build at i-install:

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/

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

Halimbawa sa 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;
}

Mga Channel App

Ideklara ang "provides": ["channel:my_channel"] at "permissions": ["channel:send"].

Ikinokonekta ng mga channel app ang mga panlabas na messaging platform (Telegram, Discord, Slack, atbp.) sa AI employee ng Nebo. Kapag nagpadala ang user ng mensahe sa panlabas na platform, ini-stream ito ng app mo sa Nebo sa pamamagitan ng Receive. Kapag gustong sumagot ng AI employee, tinatawag ng Nebo ang Send ng app mo.

Paano ito gumagana

  1. Tinatawag ng Nebo ang ID() para makuha ang natatanging identifier ng channel mo
  2. Tinatawag ng Nebo ang Connect() gamit ang config mula sa settings ng app mo
  3. Nagbubukas ang Nebo ng Receive() stream — nagpapadala ang app mo ng mga papasok na mensahe tuwing nagme-message ang user sa bot
  4. Niruruta ang mga papasok na mensahe sa pangunahing conversation lane ng AI employee
  5. Kapag gustong magpadala ng mensahe ng AI employee, tinatawag ng Nebo ang Send() gamit ang v1 message envelope
  6. Sa pag-shutdown, tinatawag ng Nebo ang Disconnect()

v1 Message Envelope

Lahat ng mensahe sa channel — papasok at palabas — ay gumagamit ng karaniwang message envelope:

{
  "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"
}
FieldUriPaglalarawan
message_idUUID v7Natatanging ID na nakaayos ayon sa oras
channel_id{type}:{platform_id}Identifier ng channel na puwedeng iruta
senderobjectPagkakakilanlan ng bot — name, role, botId
textstringKatawan ng mensahe
attachmentsarrayMga file, larawan, audio
reply_toUUID v7ID ng parent na mensahe para sa threading
actionsarrayMga interactive na button/keyboard
platform_databytesOpaque passthrough para sa mga feature na partikular sa platform
timestampISO 8601Ang publisher ang nagtatakda nito

Disenyong may dalawang layer: Sinasaklaw ng mga karaniwang field (text, attachments, reply_to, actions) ang 90% ng mga mensaheng sinimulan ng empleyado. Napupunta sa platform_data ang mga feature na partikular sa platform — ang plugin mo ang nagmamapa sa mga ito papunta at mula sa native na format ng platform.

Mga Conversation Stream

Niruruta ang mga mensahe sa channel sa mga conversation stream na hiwalay bawat channel para sa isolation:

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

Halimbawa sa Go — Telegram Channel

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

Iba pang Capability

Comm App

Ideklara ang "provides": ["comm"] at "permissions": ["comm:*"]. Pinapagana ng mga comm app ang komunikasyon sa pagitan ng mga AI employee.

FieldPaglalarawan
fromID ng nagpapadalang empleyado
toID ng tatanggap na empleyado
topicTopic/channel ng mensahe
type"message", "mention", "proposal", "command", "info", "task"
contentKatawan ng mensahe

Mga pangunahing kilos:

  • Inaanunsyo ng Register ang AI employee na ito sa network kasama ang mga capability nito
  • Pinamamahalaan ng Subscribe/Unsubscribe ang mga subscription sa topic
  • Ini-stream ng Receive ang mga papasok na mensahe (server-streaming, kapareho ng mga channel)
  • Isang comm app lang ang puwedeng aktibo sa bawat pagkakataon

Gateway App

Niruruta ng gateway app ang mga LLM request sa mga model. Ideklara ang "provides": ["gateway"] at "permissions": ["network:outbound", "user:token"].

Naglalaman ang GatewayRequest ng mga mensahe, tool, system prompt, max tokens, temperature, at isang UserContext (JWT token kung ibinigay ang user:token na pahintulot).

Mga uri ng GatewayEvent:

UriNilalamanPaglalarawan
"text"Text chunkStreaming na text token
"tool_call"JSONGustong tumawag ng model ng isang tool
"thinking"Text chunkPinalawak na pag-iisip/pangangatwiran
"error"Mensahe ng errorMay nagkaproblema
"done"Walang lamanKumpleto na ang stream

UI App

Nagbibigay ang UI app ng custom na configuration interface na bumubukas sa built-in na browser window ng Nebo. Ideklara ang "provides": ["ui"]. Hindi tulad ng awtomatikong settings form (na nire-render ng Nebo mula sa settings manifest mo), naghahain ang UI app ng sarili nitong buong HTML/CSS/JS frontend.

May kasamang ui/ directory ang app mo na naglalaman ng mga static web asset (HTML, CSS, JS — karaniwang SPA na may index.html). Direktang inihahain ng Nebo ang mga file na ito at ipinapasa ang mga API call sa app mo sa pamamagitan ng gRPC.

PathMekanismoLayunin
GET /api/v1/apps/{id}/ui/*Static file serverNaghahain ng mga file mula sa ui/ directory mo (SPA fallback sa index.html)
ANY /api/v1/apps/{id}/api/*gRPC proxyIpinapasa ang mga HTTP request sa UIService.HandleRequest() ng app mo

Binabalot ng SDK ang isang standard na net/http.ServeMux kaya karaniwang Go HTTP handler ang isusulat mo — kusang hinahawakan ng SDK ang gRPC bridging.

Halimbawa sa Go — Dashboard UI:

package main

import (
    "encoding/json"
    "log"
    "net/http"

    nebo "github.com/neboloop/nebo-sdk-go"
)

type Dashboard struct {
    mux *http.ServeMux
}

func NewDashboard() *Dashboard {
    d := &Dashboard{mux: http.NewServeMux()}

    d.mux.HandleFunc("GET /status", func(w http.ResponseWriter, r *http.Request) {
        json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
    })

    d.mux.HandleFunc("POST /action", func(w http.ResponseWriter, r *http.Request) {
        var req map[string]string
        json.NewDecoder(r.Body).Decode(&req)
        json.NewEncoder(w).Encode(map[string]string{"result": "done"})
    })

    return d
}

func (d *Dashboard) Handler() *http.ServeMux { return d.mux }

func main() {
    app, err := nebo.New()
    if err != nil {
        log.Fatal(err)
    }
    app.RegisterUI(NewDashboard())
    log.Fatal(app.Run())
}

Gagawa ang ui/index.html mo ng mga fetch call sa /api/v1/apps/com.example.dashboard/api/status, na ipinapasa papunta sa mux handler mo.

Schedule App

Pinapalitan ng schedule app ang built-in na cron scheduler ng Nebo. Ideklara ang "provides": ["schedule"] at "permissions": ["schedule:create"].

Kapag inilunsad ang schedule app mo, niruruta ng Nebo ang lahat ng pag-iskedyul sa app mo sa halip na sa default na cron engine. Kung mag-crash ang app mo, kusang babalik ang Nebo sa built-in na engine.

  • Hawak ng app mo ang schedule state — hindi iniimbak ng Nebo ang mga iskedyul sa sarili nitong DB kapag aktibo ang isang schedule app
  • Standard na CRUD: Create, Get, List, Update, Delete, Enable, Disable
  • Server-streaming RPC ang Triggers — nagpapadala ang app mo ng trigger message tuwing pumuputok ang isang iskedyul
  • Isang schedule app lang ang puwedeng aktibo sa bawat pagkakataon

Mga App na May Maraming Capability

Puwedeng magbigay ang isang app ng maraming capability. Halimbawa, isang dashboard app na may tool at 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())

Packaging

Format na .napp

Para sa distribusyon sa pamamagitan ng NeboAI, i-package ang app mo bilang .napp file (isang tar.gz archive):

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

Mga kailangang file:

FileMax na LakiPaglalarawan
manifest.json1 MBMetadata ng app
binary o app500 MBExecutable
signatures.json1 MBMga Ed25519 signature
TOOL.md1 MBMga tagubilin sa tool para sa AI employee

Mga patakaran sa seguridad habang nag-e-extract:

  • Walang path traversal (tinatanggihan ang ../)
  • Walang symlink (tinatanggihan)
  • Walang absolute path (tinatanggihan)
  • Mga filename lang na nasa allowlist ang tinatanggap

Mga Pirma

Pinipirmahan ng NeboAI ang mga app gamit ang Ed25519. Ang format ng 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>"
}

Sa dev mode (walang naka-configure na NeboAI URL), lubusang nilalaktawan ang pag-verify ng pirma. Hindi mo kailangan ng signatures.json para sa lokal na development.

Pag-publish

Kapag gumagana na ang app mo nang lokal, i-publish ito sa pamamagitan ng NeboAI para maipamahagi sa lahat ng user ng Nebo.

Pag-set up ng Developer Account

  1. Mag-register ng NeboAI account sa POST /api/v1/owners/register
  2. Mag-log in para makakuha ng JWT token: POST /api/v1/owners/login
  3. Gumawa ng developer account: POST /api/v1/developer/accounts

Daloy ng Submission

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

Hakbang 1: Gawin ang app

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

Hakbang 2: I-upload ang mga platform binary

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"

Mag-upload ng isang binary bawat platform: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Hakbang 3: I-submit para sa review

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

Proseso ng Review

  1. Awtomatikong scan — ini-scan ang mga binary sa pamamagitan ng VirusTotal
  2. Admin review — sinusuri ng team ng NeboAI ang metadata, manifest, at mga resulta ng scan
  3. Kapag naaprubahan — pinipirmahan ng NeboAI ang app gamit ang Ed25519 at ini-publish ito
  4. Kapag na-reject — makakatanggap ka ng dahilan at puwede mong ayusin at i-submit ulit

Target na tagal ng review: <24 oras.

Pag-push ng mga Update

  1. I-update ang bersyon ng app: PUT /api/v1/developer/apps/{id} kasama ang bagong bersyon
  2. Mag-upload ng mga bagong binary para sa bawat platform
  3. I-submit ulit para sa review

Dumadaan sa parehong proseso ng review ang bawat update. Nananatiling available ang mga naunang bersyon hanggang maaprubahan ang bagong bersyon.

Metadata sa Store

FieldPaglalarawan
categoryhal., productivity, communication, developer-tools
iconURL ng icon ng app
visibilitypublic o private
descriptionPuwedeng mas mahaba/mas detalyado kaysa sa paglalarawan sa manifest

Dev Workflow

Lokal na Development

Walang packaging na kailangan para sa lokal na development:

  1. Gumawa ng directory ng app mo:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Isulat ang manifest.json at code mo
  3. I-build ang binary mo:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Kusang natutuklasan ng Nebo ang bagong directory (o i-restart ang Nebo)
  5. Pagkatapos baguhin ang code, i-rebuild ang binary — ire-restart ng file watcher ang app

Pagtingin ng mga Log

Kinukuha ang stdout/stderr ng app sa mga log file na hiwalay bawat app:

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

Persistent na Data

Gamitin ang data/ directory (available din bilang NEBO_APP_DATA env var) para sa anumang file na kailangang panatilihin ng app mo. Nananatili ang directory na ito kahit may update ang app o ma-quarantine ito.

Mga Tip sa Debugging

  • Kung hindi nagsisimula ang app mo, tingnan ang logs/stderr.log para sa mga error
  • Siguraduhing executable ang binary (chmod +x binary)
  • Siguraduhing nakikinig ka sa Unix socket path mula sa NEBO_APP_SOCK
  • Dapat handa na ang socket sa loob ng 10 segundo mula sa paglulunsad
  • Gamitin ang NEBO_APP_DATA para sa storage, hindi mga hardcoded na path
  • Mag-print sa stderr para sa debug logging (kinukuha sa logs/stderr.log)

Pag-verify

# 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

Pag-uninstall

nebo apps uninstall com.example.myapp

Mga Skill

Ano ang mga Skill

Ang mga skill ay mga hanay ng tagubilin na humuhubog sa kilos ng Nebo habang may usapan. Kapag aktibo ang isang skill, direktang isinisingit ang nilalaman nito sa system prompt — ginagabayan ang tono, pamamaraan, kadalubhasaan sa larangan, at paggamit ng tool ng AI employee para sa session na iyon.

Hindi code ang mga skill. Mga markdown document ang mga ito na may YAML metadata. Walang compilation, walang binary, walang gRPC. Ang skill ay isang SKILL.md file sa isang directory. Iyon lang.

Kontekstwal at pansamantala ang mga skill. Nag-a-activate ang mga ito kapag may kaugnayan (sa pamamagitan ng trigger matching o manual na pag-load), nananatili nang ilang turn, at nag-e-expire kapag hindi na kailangan. Pinapanatili nitong magaan ang context ng AI employee — ang gabay lang na mahalaga ngayon ang nasa prompt.

Kinukumpleto ng mga skill ang mga app. Nagbibigay ang mga app ng mga executable na kakayahan (mga tool, channel, gateway). Nagbibigay ang mga skill ng gabay sa orkestrasyon — kung paano epektibong gamitin ang mga tool na iyon. Binibigyan ng calendar app ang Nebo ng kakayahang magbasa at magsulat ng mga event. Sinasabi ng isang "meeting prep" na skill sa Nebo kung paano maghanda para sa mga meeting gamit nang sabay ang calendar app na iyon, email, at web search.

Mga Skill vs Mga App

Mga SkillMga App
FormatMarkdown (SKILL.md)Compiled binary (.napp)
RuntimeIsinisingit sa system promptNaka-sandbox na proseso sa gRPC
NagbibigayGabay sa kilos, pamamaraanMga tool, channel, UI panel
TagalSaklaw ng session, nag-e-expire batay sa TTLLaging tumatakbo
PaggawaMagsulat ng markdown fileIsulat, i-compile, pirmahan, i-package
SeguridadWalang kailangang pahintulotDeny-by-default na sandbox

Quick Start

Gumawa ng directory sa Nebo skills folder mo na may SKILL.md file:

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

Magsulat ng 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.

Binabantayan ng Nebo ang skills directory gamit ang fsnotify. Available agad ang skill mo — hindi kailangang mag-restart. Magsabi ng bagay na tumutugma sa isang trigger, at kusa itong mag-a-activate.

O direktang hilingin sa Nebo: "Gumawa ng skill para sa pagsusulat ng mga blog post" — isusulat ng Nebo ang SKILL.md file para sa iyo.

Format ng SKILL.md

Bawat skill ay isang SKILL.md file na may dalawang bahagi: YAML frontmatter sa pagitan ng mga --- marker, at isang markdown body (ang mismong mga tagubiling isinisingit sa system prompt).

FieldKailanganDefaultPaglalarawan
nameOo—Natatanging identifier (nagiging slug)
descriptionOo—Isang linyang paglalarawan na ipinapakita sa skill catalog
versionHindi"1.0.0"Semver para sa pagsubaybay ng mga update
authorHindi—May-akda ng skill
priorityHindi0Mas mataas = unang itutugma (100+ para sa mga kritikal na override)
max_turnsHindi4Bilang ng turn na walang aktibidad bago kusang mag-expire
triggersHindi[]Mga pariralang kusang nag-a-activate sa skill na ito (substring match na hindi pinapansin ang laki ng titik)
toolsHindi[]Mga tool na inaasahang gagamitin ng skill na ito (pang-impormasyon)
dependenciesHindi[]Iba pang skill na dapat naka-install
tagsHindi[]Para sa pagkakategorya at pagtuklas
platformHindi[]Mga suportadong platform: macos, linux, windows (walang laman = lahat)

Paano Nag-a-activate ang mga Skill

Sumusunod ang mga skill sa modelong may dalawang yugto ng pag-activate: hint, pagkatapos invoke.

Yugto 1: Trigger Matching — Tuwing nagpapadala ang user ng mensahe, sinusuri ng Nebo ang lahat ng naka-register na skill kung may tumutugmang trigger. Lumalabas bilang mga hint sa system prompt ang mga tumutugmang skill. Nakikita ng AI employee ang hint at nagpapasya kung i-invoke ang skill.

Yugto 2: Invocation — Ini-invoke ng AI employee ang isang skill sa pamamagitan ng pagtawag sa:

skill(name: "code-review")

Ibinabalik nito ang buong SKILL.md template bilang resulta ng tool, itinatala ang invocation, at muling isinisingit ang template sa system prompt sa mga susunod na turn.

TTL at Pag-expire:

  • Mga awtomatikong itinugmang skill: 4 na turn na walang aktibidad (puwedeng i-configure sa max_turns)
  • Mga manual na na-load na skill: 6 na turn na walang aktibidad
  • Nire-reset ng muling pag-invoke ang timer
  • Mahigpit na limitasyon: hanggang 4 na aktibong skill bawat session
  • Token budget: limitado sa 16,000 character ang pinagsamang nilalaman ng mga aktibong skill

Pamamahala ng mga Skill

Mapapamahalaan ng AI employee ang mga skill sa pamamagitan ng skill tool:

ActionPaglalarawanHalimbawa
catalogIlista ang lahat ng available na skillskill(action: "catalog")
loadI-activate para sa session na itoskill(name: "code-review", action: "load")
unloadI-deactivate ang isang skillskill(name: "code-review", action: "unload")
createGumawa ng bagong skill sa diskskill(action: "create", content: "...")
updateI-update ang isang umiiral na skillskill(name: "my-skill", action: "update", content: "...")
deleteI-delete ang isang skill mula sa diskskill(name: "my-skill", action: "delete")

Pagsulat ng Mahuhusay na Skill

Ang mahusay na skill template ay may:

  1. Malinaw na heading — sinasabi sa AI employee kung anong mode ito
  2. Mga pangunahing prinsipyo — ang mga patakaran sa kilos na hindi puwedeng baguhin
  3. Pamamaraan — sunud-sunod na paraan para sa mga karaniwang sitwasyon
  4. Mga Halimbawa — mga konkretong pattern mula sa mensahe ng user hanggang sa sagot
  5. Mga anti-pattern — kung ano ang HINDI dapat gawin (natututo nang maayos ang mga model mula sa mga negatibong halimbawa)

Tip: Dapat isang bagay lang ang mahusay na ginagawa ng bawat skill. Huwag gumawa ng "general programming" na skill — gumawa ng code-review, debugging, api-design bilang magkakahiwalay na skill. Puwedeng magkaroon ng maraming aktibong skill nang sabay ang AI employee.

Mga Kasamang Skill

May kasamang mga skill ang Nebo na sumasaklaw sa mga karaniwang use case:

SkillPriyoridadPaglalarawan
onboarding100Pagbati sa bagong user at pagkolekta ng profile
best-friend50Personality skill — kaswal, tapat, prangkang usapan
debugging25Sistematikong pamamaraan sa debugging
api-design15Mga best practice sa disenyo ng RESTful API
code-review10Istrukturadong code review na may mga antas ng bigat
database-expert10Disenyo ng database, mga query, optimization
git-workflow10Git branching, mga commit, mga PR workflow
security-audit10Pagsusuri sa seguridad at pagtuklas ng kahinaan

Nagsisilbi ang mga ito bilang kapaki-pakinabang na default at reference implementation sa paggawa ng sarili mong mga skill.

Reference

Mga Proto File

Nasa proto/apps/v0/ ang mga proto file. May kasamang pre-generated na code ang mga SDK, kaya hindi mo kailangan ng protoc para sa karaniwang development.

FileServiceMga Pangunahing RPC
v0/common.proto(mga mensahe lang)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

May HealthCheck at Configure na RPC ang bawat service. Kusang hinahawakan ng SDK ang dalawa.

Mga Channel Proto Type

Uri ng MensahePaglalarawan
ChannelSendRequestPalabas na message envelope na may message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID ng mensahe sa platform para sa threading
InboundMessagePapasok na message envelope na may lahat ng karaniwang field + timestamp
MessageSenderPagkakakilanlan ng bot (name, role, botId) — dinadagdagan ng broker
AttachmentAttachment na file/larawan/audio (type, url, filename, size)
MessageActionInteractive na action ng button/keyboard (label, callback_id)

Pagkakakilanlan at mga Tungkulin ng Bot

May tatlong-axis na modelo ng pagkakakilanlan ang mga Nebo bot:

  • creature — Kung ano ang bot (archetype): "Mabilis mag-isip na strategist", "Masusing mananaliksik"
  • role — Kung ano ang kaugnayan nito sa user (relasyon): "Kaibigan", "COO", "Mentor"
  • vibe — Ang enerhiya nito (istilo ng komunikasyon): "Relax pero may opinyon", "Mainit at nakapagpapalakas ng loob"

Kapag nakatanggap ang channel plugin mo ng palabas na mensahe, naglalaman ang sender na field ng name at role ng bot. Gamitin ito para i-format ang display name para sa platform mo. Hindi job title ang role — naglalarawan ito ng relasyon. Balidong role ang "Kaibigan", "Anak", at "Mentor" kasama ng "COO" at "DevLead".