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.
| Status | Mga Wika |
|---|---|
| Suportado | Go (inirerekomenda), Rust, C/C++, Zig |
| Tinatanggihan | Python, 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
- Gumawa ng
manifest.jsonna mayid,name,version,provides - Isulat ang
TOOL.mdna naglalarawan kung paano dapat gamitin ng AI employee ang tool mo - I-install ang SDK (
go get github.com/neboloop/nebo-sdk-go) - Ipatupad ang handler interface para sa capability mo (
ToolHandler,ChannelHandler, atbp.) - I-register ang handler at tawagin ang
app.Run() - Mag-build ng native binary (
go build -o binary .) - Ilagay ang binary + manifest.json + TOOL.md sa
apps/<your-app-id>/na directory - 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:
| Field | Paglalarawan |
|---|---|
id | Reverse-domain identifier (hal., com.mycompany.myapp) |
name | Pangalang nababasa ng tao |
version | Semver string |
provides | Kahit isang capability (tingnan sa ibaba) |
Mga opsyonal na field:
| Field | Default | Paglalarawan |
|---|---|---|
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:
| Capability | gRPC Service | Paglalarawan |
|---|---|---|
gateway | GatewayService | Pagruta ng LLM model |
tool:<name> | ToolService | Isang may-pangalang tool para sa AI employee |
channel:<name> | ChannelService | Isang messaging channel |
comm | CommService | Komunikasyon sa pagitan ng mga AI employee |
ui | UIService | Custom UI na may HTTP proxy |
schedule | ScheduleService | Custom na pag-iskedyul |
vision | ToolService | Pagproseso ng vision |
browser | ToolService | Browser 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.
| Prefix | Mga Halimbawa | Paglalarawan |
|---|---|---|
network: | network:outbound, network:* | Access sa network |
filesystem: | filesystem:read, filesystem:write | Access sa file system |
memory: | memory:read, memory:write | Access sa memory ng AI employee |
session: | session:read | Mga session ng usapan |
tool: | tool:shell, tool:file | Paggamit ng ibang tool |
shell: | shell:exec | Pagpapatakbo ng shell command |
channel: | channel:send, channel:* | Mga operasyon sa channel |
comm: | comm:send, comm:* | Komunikasyon sa pagitan ng mga AI employee |
model: | model:chat | Access sa AI model |
user: | user:token | Pagtanggap ng user JWT sa mga request |
schedule: | schedule:create | Pamamahala ng cron job |
database: | database:query | Access sa database |
storage: | storage:read, storage:write | Persistent storage |
context: | context:read | Access sa context ng AI employee |
subagent: | subagent:spawn | Mga operasyon ng sub-agent |
lane: | lane:enqueue | Mga operasyon ng lane |
notification: | notification:send | Push notification |
embedding: | embedding:search | Access sa vector embedding |
skill: | skill:invoke | Pag-invoke ng skill |
advisor: | advisor:consult | Access sa advisor system |
mcp: | mcp:connect | Access sa MCP server |
voice: | voice:record | Access sa voice/audio |
browser: | browser:navigate | Browser automation |
oauth: | oauth:google, oauth:* | Access sa OAuth token |
settings: | settings:read | Access sa settings |
capability: | capability:register | Pag-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.
| Uri | Paglalarawan |
|---|---|
text | Isang linyang text input |
password | Nakatagong text input |
toggle | Boolean na on/off switch |
select | Dropdown na may nakatakdang mga opsyon |
number | Numerong input |
url | URL 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"]
}
]
} | Field | Paglalarawan |
|---|---|
provider | OAuth provider: "google", "microsoft", "github" |
scopes | Array 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:
| Variable | Halaga |
|---|---|
NEBO_APP_DIR | Installation directory ng app |
NEBO_APP_SOCK | Path papunta sa Unix socket na gagawin |
NEBO_APP_ID | App ID mula sa manifest |
NEBO_APP_NAME | Pangalan ng app mula sa manifest |
NEBO_APP_VERSION | Bersyon ng app mula sa manifest |
NEBO_APP_DATA | Path papunta sa data/ directory ng app |
PATH | System PATH (passthrough) |
HOME | Home directory ng user (passthrough) |
TMPDIR | Temp 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
- Binabasa at vina-validate ng Nebo ang
manifest.json - Hinahanap ang
binaryoappna executable sa app directory - Tinitingnan kung may
.quarantinedna marker (tumatangging ilunsad ang mga naka-quarantine na app) - Pagsusuri ng revocation (para lang sa mga app na ipinamamahagi ng NeboAI)
- Pag-verify ng pirma (para lang sa mga app na ipinamamahagi ng NeboAI, nilalaktawan sa dev)
- Pag-validate ng binary (tinatanggihan ang mga symlink, script, hindi executable, at sobrang laking file)
- Nililinis ang lumang socket mula sa nakaraang run
- Gumagawa ng
data/directory para sa naka-sandbox na storage - Nagse-set up ng mga log file bawat app (
logs/stdout.log,logs/stderr.log) - Sinisimulan ang binary gamit ang nalinis na environment at paghihiwalay ng process group
- Hinihintay na lumabas ang Unix socket (exponential backoff, hanggang 10 segundo)
- Kumokonekta sa pamamagitan ng gRPC sa Unix socket
- Gumagawa ng mga gRPC client para sa bawat capability batay sa
provides - Nagpapatakbo ng health check
- 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:
- Laging magsama ng
actionna field bilang required na string enum - Magdagdag ng
resourcena field (required na string enum) kung maraming magkakaibang uri ng resource lang ang pinamamahalaan ng tool mo - Mga parameter na para sa partikular na action ang lahat ng iba pang field
- Dapat ilista ng paglalarawan ng
actionenum ang lahat ng available na action
Bakit mahalaga ang STRAP:
- Isang beses lang natututunan ng mga LLM ang
actionrouting 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
- Tinatawag ng Nebo ang
ID()para makuha ang natatanging identifier ng channel mo - Tinatawag ng Nebo ang
Connect()gamit ang config mula sa settings ng app mo - Nagbubukas ang Nebo ng
Receive()stream — nagpapadala ang app mo ng mga papasok na mensahe tuwing nagme-message ang user sa bot - Niruruta ang mga papasok na mensahe sa pangunahing conversation lane ng AI employee
- Kapag gustong magpadala ng mensahe ng AI employee, tinatawag ng Nebo ang
Send()gamit ang v1 message envelope - 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"
} | Field | Uri | Paglalarawan |
|---|---|---|
message_id | UUID v7 | Natatanging ID na nakaayos ayon sa oras |
channel_id | {type}:{platform_id} | Identifier ng channel na puwedeng iruta |
sender | object | Pagkakakilanlan ng bot — name, role, botId |
text | string | Katawan ng mensahe |
attachments | array | Mga file, larawan, audio |
reply_to | UUID v7 | ID ng parent na mensahe para sa threading |
actions | array | Mga interactive na button/keyboard |
platform_data | bytes | Opaque passthrough para sa mga feature na partikular sa platform |
timestamp | ISO 8601 | Ang 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.
| Field | Paglalarawan |
|---|---|
from | ID ng nagpapadalang empleyado |
to | ID ng tatanggap na empleyado |
topic | Topic/channel ng mensahe |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Katawan ng mensahe |
Mga pangunahing kilos:
- Inaanunsyo ng
Registerang AI employee na ito sa network kasama ang mga capability nito - Pinamamahalaan ng
Subscribe/Unsubscribeang mga subscription sa topic - Ini-stream ng
Receiveang 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:
| Uri | Nilalaman | Paglalarawan |
|---|---|---|
"text" | Text chunk | Streaming na text token |
"tool_call" | JSON | Gustong tumawag ng model ng isang tool |
"thinking" | Text chunk | Pinalawak na pag-iisip/pangangatwiran |
"error" | Mensahe ng error | May nagkaproblema |
"done" | Walang laman | Kumpleto 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.
| Path | Mekanismo | Layunin |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Static file server | Naghahain ng mga file mula sa ui/ directory mo (SPA fallback sa index.html) |
ANY /api/v1/apps/{id}/api/* | gRPC proxy | Ipinapasa 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:
| File | Max na Laki | Paglalarawan |
|---|---|---|
manifest.json | 1 MB | Metadata ng app |
binary o app | 500 MB | Executable |
signatures.json | 1 MB | Mga Ed25519 signature |
TOOL.md | 1 MB | Mga 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
- Mag-register ng NeboAI account sa
POST /api/v1/owners/register - Mag-log in para makakuha ng JWT token:
POST /api/v1/owners/login - 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
- Awtomatikong scan — ini-scan ang mga binary sa pamamagitan ng VirusTotal
- Admin review — sinusuri ng team ng NeboAI ang metadata, manifest, at mga resulta ng scan
- Kapag naaprubahan — pinipirmahan ng NeboAI ang app gamit ang Ed25519 at ini-publish ito
- 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
- I-update ang bersyon ng app:
PUT /api/v1/developer/apps/{id}kasama ang bagong bersyon - Mag-upload ng mga bagong binary para sa bawat platform
- 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
| Field | Paglalarawan |
|---|---|
category | hal., productivity, communication, developer-tools |
icon | URL ng icon ng app |
visibility | public o private |
description | Puwedeng mas mahaba/mas detalyado kaysa sa paglalarawan sa manifest |
Dev Workflow
Lokal na Development
Walang packaging na kailangan para sa lokal na development:
- Gumawa ng directory ng app mo:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Isulat ang
manifest.jsonat code mo - I-build ang binary mo:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Kusang natutuklasan ng Nebo ang bagong directory (o i-restart ang Nebo)
- 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.logpara 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_DATApara 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 Skill | Mga App | |
|---|---|---|
| Format | Markdown (SKILL.md) | Compiled binary (.napp) |
| Runtime | Isinisingit sa system prompt | Naka-sandbox na proseso sa gRPC |
| Nagbibigay | Gabay sa kilos, pamamaraan | Mga tool, channel, UI panel |
| Tagal | Saklaw ng session, nag-e-expire batay sa TTL | Laging tumatakbo |
| Paggawa | Magsulat ng markdown file | Isulat, i-compile, pirmahan, i-package |
| Seguridad | Walang kailangang pahintulot | Deny-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).
| Field | Kailangan | Default | Paglalarawan |
|---|---|---|---|
name | Oo | — | Natatanging identifier (nagiging slug) |
description | Oo | — | Isang linyang paglalarawan na ipinapakita sa skill catalog |
version | Hindi | "1.0.0" | Semver para sa pagsubaybay ng mga update |
author | Hindi | — | May-akda ng skill |
priority | Hindi | 0 | Mas mataas = unang itutugma (100+ para sa mga kritikal na override) |
max_turns | Hindi | 4 | Bilang ng turn na walang aktibidad bago kusang mag-expire |
triggers | Hindi | [] | Mga pariralang kusang nag-a-activate sa skill na ito (substring match na hindi pinapansin ang laki ng titik) |
tools | Hindi | [] | Mga tool na inaasahang gagamitin ng skill na ito (pang-impormasyon) |
dependencies | Hindi | [] | Iba pang skill na dapat naka-install |
tags | Hindi | [] | Para sa pagkakategorya at pagtuklas |
platform | Hindi | [] | 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:
| Action | Paglalarawan | Halimbawa |
|---|---|---|
catalog | Ilista ang lahat ng available na skill | skill(action: "catalog") |
load | I-activate para sa session na ito | skill(name: "code-review", action: "load") |
unload | I-deactivate ang isang skill | skill(name: "code-review", action: "unload") |
create | Gumawa ng bagong skill sa disk | skill(action: "create", content: "...") |
update | I-update ang isang umiiral na skill | skill(name: "my-skill", action: "update", content: "...") |
delete | I-delete ang isang skill mula sa disk | skill(name: "my-skill", action: "delete") |
Pagsulat ng Mahuhusay na Skill
Ang mahusay na skill template ay may:
- Malinaw na heading — sinasabi sa AI employee kung anong mode ito
- Mga pangunahing prinsipyo — ang mga patakaran sa kilos na hindi puwedeng baguhin
- Pamamaraan — sunud-sunod na paraan para sa mga karaniwang sitwasyon
- Mga Halimbawa — mga konkretong pattern mula sa mensahe ng user hanggang sa sagot
- 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:
| Skill | Priyoridad | Paglalarawan |
|---|---|---|
onboarding | 100 | Pagbati sa bagong user at pagkolekta ng profile |
best-friend | 50 | Personality skill — kaswal, tapat, prangkang usapan |
debugging | 25 | Sistematikong pamamaraan sa debugging |
api-design | 15 | Mga best practice sa disenyo ng RESTful API |
code-review | 10 | Istrukturadong code review na may mga antas ng bigat |
database-expert | 10 | Disenyo ng database, mga query, optimization |
git-workflow | 10 | Git branching, mga commit, mga PR workflow |
security-audit | 10 | Pagsusuri 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.
| File | Service | Mga Pangunahing RPC |
|---|---|---|
v0/common.proto | (mga mensahe lang) | 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 |
May HealthCheck at Configure na RPC ang bawat service. Kusang hinahawakan ng SDK ang dalawa.
Mga Channel Proto Type
| Uri ng Mensahe | Paglalarawan |
|---|---|
ChannelSendRequest | Palabas na message envelope na may message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID ng mensahe sa platform para sa threading |
InboundMessage | Papasok na message envelope na may lahat ng karaniwang field + timestamp |
MessageSender | Pagkakakilanlan ng bot (name, role, botId) — dinadagdagan ng broker |
Attachment | Attachment na file/larawan/audio (type, url, filename, size) |
MessageAction | Interactive 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".