Visão geral
O que é o Nebo
O Nebo é um assistente pessoal de IA para desktop — um funcionário de IA sempre ativo que cuida da sua vida digital. Pense no Nebo como você pensa em um smartphone: uma plataforma poderosa que se torna transformadora graças aos seus apps.
Sozinho, o Nebo já é um funcionário de IA competente, com memória, agendamento, navegação na web, gerenciamento de arquivos e acesso ao shell. Mas o grande diferencial são os Apps. Assim como o poder de um smartphone vem do seu ecossistema de apps, o poder do Nebo vem dos apps que ampliam o que ele consegue fazer.
O que são Apps
Os Apps do Nebo são unidades independentes e pré-compiladas, com funcionalidades incríveis. Cada app dá ao Nebo um novo superpoder — gerenciamento de agenda, triagem de e-mails, acompanhamento de projetos, automação residencial, análise financeira — tudo o que um desenvolvedor puder imaginar.
Os apps oferecem um poder incrível de forma muito segura. Cada app roda em uma sandbox com permissões negadas por padrão. Ele só pode acessar o que o manifesto declara e o usuário aprova.
A interface é 100% conversacional. Os usuários não interagem com os apps por telas ou painéis separados. Eles conversam com o Nebo, e o Nebo usa as ferramentas do app para fazer as coisas. "O que tenho na agenda amanhã?" — o Nebo chama o app de agenda. "Marque uma reunião com a Sarah às 3 da tarde" — o Nebo chama o app de agenda. O usuário nunca sai da conversa.
Os apps podem, opcionalmente, oferecer uma interface de configurações — um painel de configuração que abre na janela do navegador integrado do Nebo. É ali que os usuários informam chaves de API, ativam recursos e configuram o app. A interface de configurações é gerada a partir do array settings no manifesto (o Nebo renderiza o formulário automaticamente), ou o app pode oferecer sua própria interface totalmente personalizada pela capacidade ui.
Os apps substituem e ampliam as capacidades integradas do Nebo. O Nebo vem com ferramentas básicas da plataforma (acesso à agenda local, capturas de tela etc.). Quando você instala um app de agenda, ele substitui a ferramenta de agenda integrada e se torna um superconjunto — local + nuvem + agregação + verificação de disponibilidade.
Política de apenas compilados
O Nebo aplica uma política rígida de binários exclusivamente compilados. Todos os apps precisam ser executáveis nativos compilados.
| Status | Linguagens |
|---|---|
| Aceitas | Go (recomendada), Rust, C/C++, Zig |
| Recusadas | Python, Node.js, Ruby, Java, .NET, scripts de shell |
Justificativa:
- Prevenção de automodificação pela IA — Um funcionário de IA com acesso ao shell poderia alterar o comportamento de um script interpretado em tempo de execução. Binários compilados são imutáveis depois de assinados.
- Integridade da assinatura — As assinaturas Ed25519 cobrem os bytes brutos do binário. Um binário assinado não pode ser modificado sem invalidar a assinatura.
- Aplicação da sandbox — A validação do formato binário (magic bytes ELF/Mach-O/PE) é uma barreira rápida e confiável.
Início rápido
Instale o SDK
Os SDKs oficiais cuidam de toda a configuração do servidor gRPC, do tratamento de sinais e da ponte de protocolo. Você só implementa as interfaces de handler.
Go (recomendado):
go get github.com/neboloop/nebo-sdk-go Rust (em breve):
# Coming soon
[dependencies]
nebo-sdk = "0.1" C/C++ (em breve):
# Coming soon — Add as a CMake subdirectory or copy headers from sdk/c/include/ Estrutura de diretórios do app
Os apps ficam no subdiretório apps/ do seu diretório de dados do Nebo:
~/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 mínimo do app
- Crie o
manifest.jsoncomid,name,version,provides - Escreva o
TOOL.mddescrevendo como o funcionário de IA deve usar sua ferramenta - Instale o SDK (
go get github.com/neboloop/nebo-sdk-go) - Implemente a interface de handler da sua capacidade (
ToolHandler,ChannelHandleretc.) - Registre o handler e chame
app.Run() - Compile um binário nativo (
go build -o binary .) - Coloque o binário + manifest.json + TOOL.md no diretório
apps/<your-app-id>/ - O Nebo descobre e inicia o app automaticamente
Configuração
manifest.json
Todo app precisa de um 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
}
]
} Campos obrigatórios:
| Campo | Descrição |
|---|---|
id | Identificador em domínio reverso (por exemplo, com.mycompany.myapp) |
name | Nome legível |
version | String semver |
provides | Pelo menos uma capacidade (veja abaixo) |
Campos opcionais:
| Campo | Padrão | Descrição |
|---|---|---|
runtime | "local" | "local" ou "remote" |
protocol | "grpc" | Apenas "grpc" é suportado |
permissions | [] | O que o app precisa acessar |
description | "" | Exibido na interface |
settings | [] | Configurações ajustáveis (renderizadas na interface de Configurações) |
oauth | [] | Requisitos de provedor OAuth (veja a seção OAuth abaixo) |
Capacidades
Declare o que o seu app oferece:
| Capacidade | Serviço gRPC | Descrição |
|---|---|---|
gateway | GatewayService | Roteamento de modelos LLM |
tool:<name> | ToolService | Uma ferramenta nomeada para o funcionário de IA |
channel:<name> | ChannelService | Um canal de mensagens |
comm | CommService | Comunicação entre funcionários de IA |
ui | UIService | Interface personalizada com proxy HTTP |
schedule | ScheduleService | Agendamento personalizado |
vision | ToolService | Processamento de visão |
browser | ToolService | Automação de navegador |
Um app pode oferecer várias capacidades. Por exemplo, um app pode oferecer uma ferramenta e um painel de interface ao mesmo tempo.
Permissões
As permissões controlam o que o app pode acessar. Tudo é negado por padrão — se não estiver declarado, o app não pode usar.
| Prefixo | Exemplos | Descrição |
|---|---|---|
network: | network:outbound, network:* | Acesso à rede |
filesystem: | filesystem:read, filesystem:write | Acesso ao sistema de arquivos |
memory: | memory:read, memory:write | Acesso à memória do funcionário de IA |
session: | session:read | Sessões de conversa |
tool: | tool:shell, tool:file | Usar outras ferramentas |
shell: | shell:exec | Execução de comandos de shell |
channel: | channel:send, channel:* | Operações de canal |
comm: | comm:send, comm:* | Comunicação entre funcionários de IA |
model: | model:chat | Acesso a modelos de IA |
user: | user:token | Receber o JWT do usuário nas requisições |
schedule: | schedule:create | Gerenciamento de tarefas cron |
database: | database:query | Acesso ao banco de dados |
storage: | storage:read, storage:write | Armazenamento persistente |
context: | context:read | Acesso ao contexto do funcionário de IA |
subagent: | subagent:spawn | Operações de subagentes |
lane: | lane:enqueue | Operações de lanes |
notification: | notification:send | Notificações push |
embedding: | embedding:search | Acesso a embeddings vetoriais |
skill: | skill:invoke | Invocação de skills |
advisor: | advisor:consult | Acesso ao sistema de consultores |
mcp: | mcp:connect | Acesso a servidores MCP |
voice: | voice:record | Acesso a voz/áudio |
browser: | browser:navigate | Automação de navegador |
oauth: | oauth:google, oauth:* | Acesso a tokens OAuth |
settings: | settings:read | Acesso às configurações |
capability: | capability:register | Registro de capacidades |
Permissões curinga são suportadas: network:* corresponde a qualquer verificação de permissão network:.
Configurações
As configurações aparecem na interface do Nebo, no painel de configurações do app. O Nebo as armazena no banco de dados e as envia para o seu app pela RPC Configure sempre que elas mudam.
O esquema de configurações é incluído na página do app na loja da NeboAI. Apps com configurações obrigatórias não preenchidas exibem o selo "Precisa de configuração" na interface.
| Tipo | Descrição |
|---|---|
text | Campo de texto de uma linha |
password | Campo de texto mascarado |
toggle | Chave liga/desliga booleana |
select | Menu suspenso com opções predefinidas |
number | Campo numérico |
url | Campo de URL com validação |
{
"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"}
]
} Requisitos de OAuth
Os apps podem declarar requisitos de provedor OAuth. O broker OAuth do Nebo cuida de todo o fluxo — os apps recebem os tokens automaticamente pela RPC Configure.
{
"oauth": [
{
"provider": "google",
"scopes": ["https://www.googleapis.com/auth/calendar"]
}
]
} | Campo | Descrição |
|---|---|
provider | Provedor OAuth: "google", "microsoft", "github" |
scopes | Array de escopos OAuth de que o app precisa |
Quando o usuário instala o app, o Nebo pede que ele autorize os escopos OAuth necessários. O app recebe tokens renovados pela RPC Configure sem precisar cuidar do fluxo OAuth.
Variáveis de ambiente
O processo do seu app recebe um ambiente higienizado. Todos os segredos são removidos. Você recebe:
| Variável | Valor |
|---|---|
NEBO_APP_DIR | Diretório de instalação do app |
NEBO_APP_SOCK | Caminho do socket Unix a ser criado |
NEBO_APP_ID | ID do app no manifesto |
NEBO_APP_NAME | Nome do app no manifesto |
NEBO_APP_VERSION | Versão do app no manifesto |
NEBO_APP_DATA | Caminho do diretório data/ do app |
PATH | PATH do sistema (repassado) |
HOME | Diretório home do usuário (repassado) |
TMPDIR | Diretório temporário (repassado) |
Importante: seu binário precisa criar um servidor gRPC escutando no socket Unix em NEBO_APP_SOCK. O Nebo espera até 10 segundos para esse socket aparecer.
Sequência de inicialização do app
- O Nebo lê o
manifest.jsone o valida - Encontra o executável
binaryouappno diretório do app - Verifica o marcador
.quarantined(não inicia apps em quarentena) - Verificação de revogação (somente apps distribuídos pela NeboAI)
- Verificação de assinatura (somente apps distribuídos pela NeboAI; ignorada em desenvolvimento)
- Validação do binário (recusa symlinks, scripts, arquivos não executáveis e arquivos grandes demais)
- Remove o socket antigo da execução anterior
- Cria o diretório
data/para armazenamento em sandbox - Configura arquivos de log por app (
logs/stdout.log,logs/stderr.log) - Inicia o binário com ambiente higienizado e isolamento de grupo de processos
- Espera o socket Unix aparecer (backoff exponencial, no máximo 10 segundos)
- Conecta via gRPC pelo socket Unix
- Cria clientes gRPC específicos de cada capacidade com base em
provides - Executa a verificação de integridade
- Registra as capacidades no funcionário de IA (ferramentas, gateway, comm etc.)
Apps de ferramenta
Declare "provides": ["tool:my_tool_name"] no seu manifesto.
O padrão STRAP
Todos os apps de ferramenta do Nebo precisam usar o STRAP (Single Tool Resource Action Pattern) no esquema e no roteamento da execução. É o mesmo padrão que o Nebo usa internamente para consolidar mais de 35 ferramentas individuais em 4 ferramentas de domínio — reduzindo a sobrecarga de contexto do LLM em cerca de 80%.
Ideia central: em vez de registrar várias ferramentas (get_events, check_availability, suggest_slots), registre UMA ferramenta com campos action (e, opcionalmente, resource) que direcionam para o handler certo.
Exemplo com um recurso (agenda):
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") Exemplo com vários recursos (gerenciador de projetos):
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") Regras do esquema:
- Sempre inclua um campo
actioncomo enum de string obrigatório - Adicione um campo
resource(enum de string obrigatório) somente se a sua ferramenta gerenciar vários tipos de recurso distintos - Todos os outros campos são parâmetros específicos de cada ação
- A descrição do enum
actiondeve listar todas as ações disponíveis
Por que o STRAP importa:
- Os LLMs aprendem o padrão de roteamento por
actionuma vez e o generalizam para todas as operações - As definições de ferramentas consomem cerca de 6% do contexto — o STRAP reduz isso em 80%
- Novas operações são apenas novos valores no enum, não novos registros de ferramenta
- Funciona do mesmo jeito em modelos hospedados e locais
Exemplo em Go — Ferramenta de calculadora
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": []
} Compile e instale:
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/ Exemplo em 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(())
} Exemplo em 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;
} Apps de canal
Declare "provides": ["channel:my_channel"] e "permissions": ["channel:send"].
Os apps de canal conectam plataformas de mensagens externas (Telegram, Discord, Slack etc.) ao funcionário de IA do Nebo. Quando um usuário envia uma mensagem na plataforma externa, seu app a transmite ao Nebo via Receive. Quando o funcionário de IA quer responder, o Nebo chama o Send do seu app.
Como funciona
- O Nebo chama
ID()para obter o identificador único do seu canal - O Nebo chama
Connect()com a configuração vinda das configurações do seu app - O Nebo abre um stream
Receive()— seu app envia as mensagens recebidas sempre que um usuário manda mensagem para o bot - As mensagens recebidas são direcionadas para a lane de conversa principal do funcionário de IA
- Quando o funcionário de IA quer enviar uma mensagem, o Nebo chama
Send()com o envelope de mensagem v1 - No encerramento, o Nebo chama
Disconnect()
Envelope de mensagem v1
Todas as mensagens de canal — recebidas e enviadas — usam o envelope de mensagem comum:
{
"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"
} | Campo | Tipo | Descrição |
|---|---|---|
message_id | UUID v7 | ID único ordenado por tempo |
channel_id | {type}:{platform_id} | Identificador de canal roteável |
sender | object | Identidade do bot — nome, função, botId |
text | string | Corpo da mensagem |
attachments | array | Arquivos, imagens, áudio |
reply_to | UUID v7 | ID da mensagem pai, para threads |
actions | array | Botões/teclados interativos |
platform_data | bytes | Repasse opaco para recursos específicos da plataforma |
timestamp | ISO 8601 | Definido pelo publicador |
Design em duas camadas: os campos comuns (text, attachments, reply_to, actions) cobrem 90% das mensagens iniciadas pelo funcionário. Recursos específicos da plataforma ficam em platform_data — seu plugin faz a conversão de e para o formato nativo da plataforma.
Streams de conversa
As mensagens de canal trafegam por streams de conversa separados por canal, para garantir isolamento:
neboai/bot/{botID}/channels/{channelType}/inbound # messages from users → agent
neboai/bot/{botID}/channels/{channelType}/outbound # messages from agent → channel Exemplo em Go — Canal do 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
}
]
} Mais capacidades
App de comunicação
Declare "provides": ["comm"] e "permissions": ["comm:*"]. Os apps de comunicação permitem a comunicação entre funcionários de IA.
| Campo | Descrição |
|---|---|
from | ID do funcionário remetente |
to | ID do funcionário destinatário |
topic | Tópico/canal da mensagem |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Corpo da mensagem |
Comportamentos principais:
Registeranuncia este funcionário de IA na rede, com as capacidades deleSubscribe/Unsubscribegerenciam as inscrições em tópicosReceivetransmite as mensagens recebidas (server-streaming, igual aos canais)- Só um app de comunicação pode ficar ativo por vez
App de gateway
Um app de gateway encaminha requisições de LLM para os modelos. Declare "provides": ["gateway"] e "permissions": ["network:outbound", "user:token"].
GatewayRequest contém mensagens, ferramentas, prompt de sistema, máximo de tokens, temperatura e um UserContext (token JWT, se a permissão user:token for concedida).
Tipos de GatewayEvent:
| Tipo | Conteúdo | Descrição |
|---|---|---|
"text" | Trecho de texto | Token de texto em streaming |
"tool_call" | JSON | O modelo quer chamar uma ferramenta |
"thinking" | Trecho de texto | Raciocínio estendido |
"error" | Mensagem de erro | Algo deu errado |
"done" | Vazio | O stream terminou |
App de interface
Um app de interface oferece uma tela de configuração personalizada que abre na janela do navegador integrado do Nebo. Declare "provides": ["ui"]. Diferente do formulário de configurações automático (que o Nebo renderiza a partir do settings do seu manifesto), um app de interface serve seu próprio frontend completo em HTML/CSS/JS.
Seu app inclui um diretório ui/ com arquivos web estáticos (HTML, CSS, JS — normalmente uma SPA com index.html). O Nebo serve esses arquivos diretamente e repassa as chamadas de API para o seu app via gRPC.
| Caminho | Mecanismo | Finalidade |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Servidor de arquivos estáticos | Serve os arquivos do seu diretório ui/ (com fallback de SPA para index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Repassa requisições HTTP para o UIService.HandleRequest() do seu app |
O SDK encapsula um net/http.ServeMux padrão, então você escreve handlers HTTP comuns em Go — o SDK cuida da ponte gRPC automaticamente.
Exemplo em Go — Interface de dashboard:
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())
} Seu ui/index.html faria chamadas fetch para /api/v1/apps/com.example.dashboard/api/status, que são repassadas para o seu handler mux.
App de agendamento
Um app de agendamento substitui o agendador cron integrado do Nebo. Declare "provides": ["schedule"] e "permissions": ["schedule:create"].
Quando o seu app de agendamento inicia, o Nebo passa a direcionar todo o agendamento para ele em vez do motor cron padrão. Se o seu app travar, o Nebo volta automaticamente para o motor integrado.
- Seu app é dono do estado dos agendamentos — o Nebo não guarda agendamentos no próprio banco de dados enquanto um app de agendamento estiver ativo
- CRUD padrão:
Create,Get,List,Update,Delete,Enable,Disable Triggersé uma RPC de server-streaming — seu app envia uma mensagem de disparo sempre que um agendamento é acionado- Só um app de agendamento pode ficar ativo por vez
Apps com várias capacidades
Um app pode oferecer várias capacidades. Por exemplo, um app de dashboard com uma ferramenta e uma interface:
{
"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()) Empacotamento
Formato .napp
Para distribuir pela NeboAI, empacote seu app como um arquivo .napp (um arquivo tar.gz):
cd com.example.myapp/
tar -czf myapp-1.0.0.napp manifest.json binary signatures.json TOOL.md Arquivos obrigatórios:
| Arquivo | Tamanho máximo | Descrição |
|---|---|---|
manifest.json | 1 MB | Metadados do app |
binary ou app | 500 MB | Executável |
signatures.json | 1 MB | Assinaturas Ed25519 |
TOOL.md | 1 MB | Instruções da ferramenta para o funcionário de IA |
Regras de segurança na extração:
- Sem path traversal (
../é recusado) - Sem symlinks (recusados)
- Sem caminhos absolutos (recusados)
- Só nomes de arquivo da lista permitida são aceitos
Assinaturas
A NeboAI assina os apps com Ed25519. O formato do 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>"
} No modo de desenvolvimento (sem URL da NeboAI configurada), a verificação de assinatura é totalmente ignorada. Você não precisa de signatures.json para desenvolver localmente.
Publicação
Quando o seu app estiver funcionando localmente, publique-o pela NeboAI para distribuí-lo a todos os usuários do Nebo.
Configuração da conta de desenvolvedor
- Crie uma conta NeboAI em
POST /api/v1/owners/register - Faça login para obter um token JWT:
POST /api/v1/owners/login - Crie uma conta de desenvolvedor:
POST /api/v1/developer/accounts
Fluxo de envio
draft → pending_review → [approved] → published
→ [rejected] → draft (fix and resubmit) Passo 1: Crie o 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"
}' Passo 2: Envie os binários de cada plataforma
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" Envie um binário por plataforma: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.
Passo 3: Envie para revisão
curl -X POST https://neboai.com/api/v1/developer/apps/{id}/submit \
-H "Authorization: Bearer $TOKEN" Processo de revisão
- Verificação automática — os binários são analisados pelo VirusTotal
- Revisão administrativa — a equipe da NeboAI revisa os metadados, o manifesto e os resultados da verificação
- Na aprovação — a NeboAI assina o app com Ed25519 e o publica
- Na recusa — você recebe o motivo e pode corrigir e reenviar
Prazo de revisão previsto: <24 horas.
Publicação de atualizações
- Atualize a versão do app:
PUT /api/v1/developer/apps/{id}com a nova versão - Envie novos binários para cada plataforma
- Envie para revisão novamente
Cada atualização passa pelo mesmo processo de revisão. As versões anteriores continuam disponíveis até a nova versão ser aprovada.
Metadados da loja
| Campo | Descrição |
|---|---|
category | por exemplo, productivity, communication, developer-tools |
icon | URL do ícone do app |
visibility | public ou private |
description | Pode ser mais longa e detalhada que a descrição do manifesto |
Fluxo de desenvolvimento
Desenvolvimento local
Não é preciso empacotar nada para desenvolver localmente:
- Crie o diretório do seu app:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Escreva o seu
manifest.jsone o código - Compile seu binário:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - O Nebo detecta o novo diretório automaticamente (ou reinicie o Nebo)
- Depois de alterar o código, recompile o binário — o observador de arquivos vai reiniciar o app
Ver os logs
O stdout/stderr do app é capturado em arquivos de log por 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 Dados persistentes
Use o diretório data/ (também disponível na variável de ambiente NEBO_APP_DATA) para qualquer arquivo que o seu app precise manter. Esse diretório sobrevive a atualizações do app e à quarentena.
Dicas de depuração
- Se o seu app não iniciar, procure erros em
logs/stderr.log - Verifique se o binário é executável (
chmod +x binary) - Confirme que você está escutando no caminho de socket Unix indicado em
NEBO_APP_SOCK - O socket precisa estar pronto em até 10 segundos após a inicialização
- Use
NEBO_APP_DATApara armazenamento, não caminhos fixos no código - Escreva no stderr para logs de depuração (capturados em
logs/stderr.log)
Verificação
# 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 Desinstalação
nebo apps uninstall com.example.myapp Skills
O que são skills
Skills são conjuntos de instruções que moldam o comportamento do Nebo durante uma conversa. Quando uma skill está ativa, o conteúdo dela é injetado diretamente no prompt de sistema — orientando o tom, a metodologia, o conhecimento especializado e o uso de ferramentas do funcionário de IA naquela sessão.
Skills não são código. São documentos markdown com metadados YAML. Sem compilação, sem binário, sem gRPC. Uma skill é um arquivo SKILL.md dentro de um diretório. Só isso.
Skills são contextuais e temporárias. Elas são ativadas quando fazem sentido (por correspondência de gatilho ou carregamento manual), permanecem por alguns turnos e expiram quando deixam de ser necessárias. Isso mantém o contexto do funcionário de IA enxuto — só a orientação que importa agora fica no prompt.
Skills complementam os apps. Os apps oferecem capacidades executáveis (ferramentas, canais, gateways). As skills oferecem orientação de orquestração — como usar essas ferramentas de forma eficaz. Um app de agenda dá ao Nebo a capacidade de ler e criar eventos. Uma skill de "preparação de reuniões" diz ao Nebo como se preparar para reuniões usando esse app de agenda, o e-mail e a busca na web juntos.
Skills vs. apps
| Skills | Apps | |
|---|---|---|
| Formato | Markdown (SKILL.md) | Binário compilado (.napp) |
| Execução | Injetada no prompt de sistema | Processo em sandbox via gRPC |
| Oferece | Orientação de comportamento, metodologia | Ferramentas, canais, painéis de interface |
| Duração | Limitada à sessão, expira por TTL | Sempre em execução |
| Criação | Escrever um arquivo markdown | Escrever, compilar, assinar, empacotar |
| Segurança | Nenhuma permissão necessária | Sandbox com tudo negado por padrão |
Início rápido
Crie um diretório na sua pasta de skills do Nebo com um arquivo SKILL.md:
~/Library/Application Support/Nebo/skills/ # macOS
~/.config/nebo/skills/ # Linux
%AppData%\Nebo\skills\ # Windows mkdir -p ~/.config/nebo/skills/my-skill Escreva um 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. O Nebo monitora o diretório de skills com fsnotify. Sua skill fica disponível na hora — sem precisar reiniciar. Diga algo que corresponda a um gatilho e ela é ativada automaticamente.
Ou peça diretamente ao Nebo: "Crie uma skill para escrever posts de blog" — o Nebo escreve o arquivo SKILL.md para você.
Formato do SKILL.md
Toda skill é um único arquivo SKILL.md com duas partes: um frontmatter YAML entre marcadores --- e um corpo em markdown (as instruções de fato injetadas no prompt de sistema).
| Campo | Obrigatório | Padrão | Descrição |
|---|---|---|---|
name | Sim | — | Identificador único (vira o slug) |
description | Sim | — | Descrição de uma linha exibida no catálogo de skills |
version | Não | "1.0.0" | Semver para acompanhar atualizações |
author | Não | — | Autor da skill |
priority | Não | 0 | Maior = verificada primeiro (100+ para substituições críticas) |
max_turns | Não | 4 | Turnos de inatividade antes de expirar automaticamente |
triggers | Não | [] | Frases que ativam esta skill automaticamente (correspondência de substring, sem diferenciar maiúsculas e minúsculas) |
tools | Não | [] | Ferramentas que esta skill pretende usar (informativo) |
dependencies | Não | [] | Outras skills que precisam estar instaladas |
tags | Não | [] | Para categorização e descoberta |
platform | Não | [] | Plataformas suportadas: macos, linux, windows (vazio = todas) |
Como as skills são ativadas
As skills seguem um modelo de ativação em duas fases: sugestão e depois invocação.
Fase 1: Correspondência de gatilhos — Sempre que um usuário envia uma mensagem, o Nebo verifica todas as skills registradas em busca de gatilhos correspondentes. As skills correspondentes aparecem como sugestões no prompt de sistema. O funcionário de IA vê a sugestão e decide se invoca a skill.
Fase 2: Invocação — O funcionário de IA invoca uma skill chamando:
skill(name: "code-review") Isso retorna o template completo do SKILL.md como resultado da ferramenta, registra a invocação e volta a injetar o template no prompt de sistema nos turnos seguintes.
TTL e expiração:
- Skills ativadas automaticamente: 4 turnos de inatividade (configurável via
max_turns) - Skills carregadas manualmente: 6 turnos de inatividade
- Invocar de novo reinicia o contador
- Limite rígido: no máximo 4 skills ativas por sessão
- Orçamento de tokens: o conteúdo somado das skills ativas é limitado a 16.000 caracteres
Gerenciar skills
O funcionário de IA pode gerenciar skills pela ferramenta skill:
| Ação | Descrição | Exemplo |
|---|---|---|
catalog | Listar todas as skills disponíveis | skill(action: "catalog") |
load | Ativar nesta sessão | skill(name: "code-review", action: "load") |
unload | Desativar uma skill | skill(name: "code-review", action: "unload") |
create | Criar uma nova skill no disco | skill(action: "create", content: "...") |
update | Atualizar uma skill existente | skill(name: "my-skill", action: "update", content: "...") |
delete | Excluir uma skill do disco | skill(name: "my-skill", action: "delete") |
Como escrever boas skills
Um bom template de skill tem:
- Um título claro — diz ao funcionário de IA em que modo ele está
- Princípios centrais — as regras de comportamento inegociáveis
- Metodologia — uma abordagem passo a passo para cenários comuns
- Exemplos — padrões concretos de mensagem do usuário e resposta
- Antipadrões — o que NÃO fazer (os modelos aprendem bem com exemplos negativos)
Dica: cada skill deve fazer uma coisa bem feita. Não crie uma skill de "programação geral" — crie code-review, debugging e api-design como skills separadas. O funcionário de IA pode ter várias ativas ao mesmo tempo.
Skills incluídas
O Nebo vem com skills incluídas que cobrem casos de uso comuns:
| Skill | Prioridade | Descrição |
|---|---|---|
onboarding | 100 | Boas-vindas a novos usuários e coleta de perfil |
best-friend | 50 | Skill de personalidade — descontraída, leal, papo reto |
debugging | 25 | Metodologia sistemática de depuração |
api-design | 15 | Boas práticas de design de APIs RESTful |
code-review | 10 | Revisão de código estruturada com níveis de gravidade |
database-expert | 10 | Design de banco de dados, consultas, otimização |
git-workflow | 10 | Branches, commits e fluxos de PR no Git |
security-audit | 10 | Análise de segurança e detecção de vulnerabilidades |
Elas servem tanto como padrões úteis quanto como implementações de referência para você criar suas próprias skills.
Referência
Arquivos proto
Os arquivos proto ficam em proto/apps/v0/. Os SDKs já vêm com código pré-gerado, então você não precisa do protoc no desenvolvimento normal.
| Arquivo | Serviço | RPCs principais |
|---|---|---|
v0/common.proto | (apenas mensagens) | 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 |
Todo serviço inclui as RPCs HealthCheck e Configure. O SDK cuida das duas automaticamente.
Tipos proto de canal
| Tipo de mensagem | Descrição |
|---|---|
ChannelSendRequest | Envelope de mensagem enviada com message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID da mensagem na plataforma, para threads |
InboundMessage | Envelope de mensagem recebida com todos os campos comuns + timestamp |
MessageSender | Identidade do bot (name, role, botId) — enriquecida pelo broker |
Attachment | Anexo de arquivo/imagem/áudio (type, url, filename, size) |
MessageAction | Ação interativa de botão/teclado (label, callback_id) |
Identidade e papéis dos bots
Os bots do Nebo têm um modelo de identidade em três eixos:
- creature — O que o bot é (arquétipo): "Estrategista perspicaz", "Pesquisador meticuloso"
- role — Como ele se relaciona com o usuário (relação): "Amigo", "COO", "Mentor"
- vibe — A energia dele (estilo de comunicação): "Tranquilo, mas opinativo", "Caloroso e encorajador"
Quando o seu plugin de canal recebe uma mensagem de saída, o campo sender contém o name e o role do bot. Use isso para formatar o nome exibido na sua plataforma. O papel não é um cargo — é uma descrição de relação. "Amigo", "Filho" e "Mentor" são papéis válidos, assim como "COO" e "DevLead".