NeboAI
NeboAI
Começar

Crie apps para o Nebo

Dê novos superpoderes à sua IA. Ferramentas, canais, gateways, painéis de interface — tudo o que você imaginar, compilado em um binário nativo.

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.

StatusLinguagens
AceitasGo (recomendada), Rust, C/C++, Zig
RecusadasPython, 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

  1. Crie o manifest.json com id, name, version, provides
  2. Escreva o TOOL.md descrevendo como o funcionário de IA deve usar sua ferramenta
  3. Instale o SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Implemente a interface de handler da sua capacidade (ToolHandler, ChannelHandler etc.)
  5. Registre o handler e chame app.Run()
  6. Compile um binário nativo (go build -o binary .)
  7. Coloque o binário + manifest.json + TOOL.md no diretório apps/<your-app-id>/
  8. 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:

CampoDescrição
idIdentificador em domínio reverso (por exemplo, com.mycompany.myapp)
nameNome legível
versionString semver
providesPelo menos uma capacidade (veja abaixo)

Campos opcionais:

CampoPadrãoDescriçã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:

CapacidadeServiço gRPCDescrição
gatewayGatewayServiceRoteamento de modelos LLM
tool:<name>ToolServiceUma ferramenta nomeada para o funcionário de IA
channel:<name>ChannelServiceUm canal de mensagens
commCommServiceComunicação entre funcionários de IA
uiUIServiceInterface personalizada com proxy HTTP
scheduleScheduleServiceAgendamento personalizado
visionToolServiceProcessamento de visão
browserToolServiceAutomaçã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.

PrefixoExemplosDescrição
network:network:outbound, network:*Acesso à rede
filesystem:filesystem:read, filesystem:writeAcesso ao sistema de arquivos
memory:memory:read, memory:writeAcesso à memória do funcionário de IA
session:session:readSessões de conversa
tool:tool:shell, tool:fileUsar outras ferramentas
shell:shell:execExecuçã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:chatAcesso a modelos de IA
user:user:tokenReceber o JWT do usuário nas requisições
schedule:schedule:createGerenciamento de tarefas cron
database:database:queryAcesso ao banco de dados
storage:storage:read, storage:writeArmazenamento persistente
context:context:readAcesso ao contexto do funcionário de IA
subagent:subagent:spawnOperações de subagentes
lane:lane:enqueueOperações de lanes
notification:notification:sendNotificações push
embedding:embedding:searchAcesso a embeddings vetoriais
skill:skill:invokeInvocação de skills
advisor:advisor:consultAcesso ao sistema de consultores
mcp:mcp:connectAcesso a servidores MCP
voice:voice:recordAcesso a voz/áudio
browser:browser:navigateAutomação de navegador
oauth:oauth:google, oauth:*Acesso a tokens OAuth
settings:settings:readAcesso às configurações
capability:capability:registerRegistro 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.

TipoDescrição
textCampo de texto de uma linha
passwordCampo de texto mascarado
toggleChave liga/desliga booleana
selectMenu suspenso com opções predefinidas
numberCampo numérico
urlCampo 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"]
        }
    ]
}
CampoDescrição
providerProvedor OAuth: "google", "microsoft", "github"
scopesArray 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ávelValor
NEBO_APP_DIRDiretório de instalação do app
NEBO_APP_SOCKCaminho do socket Unix a ser criado
NEBO_APP_IDID do app no manifesto
NEBO_APP_NAMENome do app no manifesto
NEBO_APP_VERSIONVersão do app no manifesto
NEBO_APP_DATACaminho do diretório data/ do app
PATHPATH do sistema (repassado)
HOMEDiretório home do usuário (repassado)
TMPDIRDiretó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

  1. O Nebo lê o manifest.json e o valida
  2. Encontra o executável binary ou app no diretório do app
  3. Verifica o marcador .quarantined (não inicia apps em quarentena)
  4. Verificação de revogação (somente apps distribuídos pela NeboAI)
  5. Verificação de assinatura (somente apps distribuídos pela NeboAI; ignorada em desenvolvimento)
  6. Validação do binário (recusa symlinks, scripts, arquivos não executáveis e arquivos grandes demais)
  7. Remove o socket antigo da execução anterior
  8. Cria o diretório data/ para armazenamento em sandbox
  9. Configura arquivos de log por app (logs/stdout.log, logs/stderr.log)
  10. Inicia o binário com ambiente higienizado e isolamento de grupo de processos
  11. Espera o socket Unix aparecer (backoff exponencial, no máximo 10 segundos)
  12. Conecta via gRPC pelo socket Unix
  13. Cria clientes gRPC específicos de cada capacidade com base em provides
  14. Executa a verificação de integridade
  15. 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:

  1. Sempre inclua um campo action como enum de string obrigatório
  2. Adicione um campo resource (enum de string obrigatório) somente se a sua ferramenta gerenciar vários tipos de recurso distintos
  3. Todos os outros campos são parâmetros específicos de cada ação
  4. A descrição do enum action deve listar todas as ações disponíveis

Por que o STRAP importa:

  • Os LLMs aprendem o padrão de roteamento por action uma 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

  1. O Nebo chama ID() para obter o identificador único do seu canal
  2. O Nebo chama Connect() com a configuração vinda das configurações do seu app
  3. O Nebo abre um stream Receive() — seu app envia as mensagens recebidas sempre que um usuário manda mensagem para o bot
  4. As mensagens recebidas são direcionadas para a lane de conversa principal do funcionário de IA
  5. Quando o funcionário de IA quer enviar uma mensagem, o Nebo chama Send() com o envelope de mensagem v1
  6. 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"
}
CampoTipoDescrição
message_idUUID v7ID único ordenado por tempo
channel_id{type}:{platform_id}Identificador de canal roteável
senderobjectIdentidade do bot — nome, função, botId
textstringCorpo da mensagem
attachmentsarrayArquivos, imagens, áudio
reply_toUUID v7ID da mensagem pai, para threads
actionsarrayBotões/teclados interativos
platform_databytesRepasse opaco para recursos específicos da plataforma
timestampISO 8601Definido 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.

CampoDescrição
fromID do funcionário remetente
toID do funcionário destinatário
topicTópico/canal da mensagem
type"message", "mention", "proposal", "command", "info", "task"
contentCorpo da mensagem

Comportamentos principais:

  • Register anuncia este funcionário de IA na rede, com as capacidades dele
  • Subscribe/Unsubscribe gerenciam as inscrições em tópicos
  • Receive transmite 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:

TipoConteúdoDescrição
"text"Trecho de textoToken de texto em streaming
"tool_call"JSONO modelo quer chamar uma ferramenta
"thinking"Trecho de textoRaciocínio estendido
"error"Mensagem de erroAlgo deu errado
"done"VazioO 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.

CaminhoMecanismoFinalidade
GET /api/v1/apps/{id}/ui/*Servidor de arquivos estáticosServe os arquivos do seu diretório ui/ (com fallback de SPA para index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCRepassa 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:

ArquivoTamanho máximoDescrição
manifest.json1 MBMetadados do app
binary ou app500 MBExecutável
signatures.json1 MBAssinaturas Ed25519
TOOL.md1 MBInstruçõ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

  1. Crie uma conta NeboAI em POST /api/v1/owners/register
  2. Faça login para obter um token JWT: POST /api/v1/owners/login
  3. 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

  1. Verificação automática — os binários são analisados pelo VirusTotal
  2. Revisão administrativa — a equipe da NeboAI revisa os metadados, o manifesto e os resultados da verificação
  3. Na aprovação — a NeboAI assina o app com Ed25519 e o publica
  4. Na recusa — você recebe o motivo e pode corrigir e reenviar

Prazo de revisão previsto: <24 horas.

Publicação de atualizações

  1. Atualize a versão do app: PUT /api/v1/developer/apps/{id} com a nova versão
  2. Envie novos binários para cada plataforma
  3. 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

CampoDescrição
categorypor exemplo, productivity, communication, developer-tools
iconURL do ícone do app
visibilitypublic ou private
descriptionPode ser mais longa e detalhada que a descrição do manifesto

Fluxo de desenvolvimento

Desenvolvimento local

Não é preciso empacotar nada para desenvolver localmente:

  1. Crie o diretório do seu app:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Escreva o seu manifest.json e o código
  3. Compile seu binário:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. O Nebo detecta o novo diretório automaticamente (ou reinicie o Nebo)
  5. 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_DATA para 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

SkillsApps
FormatoMarkdown (SKILL.md)Binário compilado (.napp)
ExecuçãoInjetada no prompt de sistemaProcesso em sandbox via gRPC
OfereceOrientação de comportamento, metodologiaFerramentas, canais, painéis de interface
DuraçãoLimitada à sessão, expira por TTLSempre em execução
CriaçãoEscrever um arquivo markdownEscrever, compilar, assinar, empacotar
SegurançaNenhuma permissão necessáriaSandbox 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).

CampoObrigatórioPadrãoDescrição
nameSim—Identificador único (vira o slug)
descriptionSim—Descrição de uma linha exibida no catálogo de skills
versionNão"1.0.0"Semver para acompanhar atualizações
authorNão—Autor da skill
priorityNão0Maior = verificada primeiro (100+ para substituições críticas)
max_turnsNão4Turnos de inatividade antes de expirar automaticamente
triggersNão[]Frases que ativam esta skill automaticamente (correspondência de substring, sem diferenciar maiúsculas e minúsculas)
toolsNão[]Ferramentas que esta skill pretende usar (informativo)
dependenciesNão[]Outras skills que precisam estar instaladas
tagsNão[]Para categorização e descoberta
platformNã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çãoDescriçãoExemplo
catalogListar todas as skills disponíveisskill(action: "catalog")
loadAtivar nesta sessãoskill(name: "code-review", action: "load")
unloadDesativar uma skillskill(name: "code-review", action: "unload")
createCriar uma nova skill no discoskill(action: "create", content: "...")
updateAtualizar uma skill existenteskill(name: "my-skill", action: "update", content: "...")
deleteExcluir uma skill do discoskill(name: "my-skill", action: "delete")

Como escrever boas skills

Um bom template de skill tem:

  1. Um título claro — diz ao funcionário de IA em que modo ele está
  2. Princípios centrais — as regras de comportamento inegociáveis
  3. Metodologia — uma abordagem passo a passo para cenários comuns
  4. Exemplos — padrões concretos de mensagem do usuário e resposta
  5. 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:

SkillPrioridadeDescrição
onboarding100Boas-vindas a novos usuários e coleta de perfil
best-friend50Skill de personalidade — descontraída, leal, papo reto
debugging25Metodologia sistemática de depuração
api-design15Boas práticas de design de APIs RESTful
code-review10Revisão de código estruturada com níveis de gravidade
database-expert10Design de banco de dados, consultas, otimização
git-workflow10Branches, commits e fluxos de PR no Git
security-audit10Aná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.

ArquivoServiçoRPCs principais
v0/common.proto(apenas mensagens)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

Todo serviço inclui as RPCs HealthCheck e Configure. O SDK cuida das duas automaticamente.

Tipos proto de canal

Tipo de mensagemDescrição
ChannelSendRequestEnvelope de mensagem enviada com message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID da mensagem na plataforma, para threads
InboundMessageEnvelope de mensagem recebida com todos os campos comuns + timestamp
MessageSenderIdentidade do bot (name, role, botId) — enriquecida pelo broker
AttachmentAnexo de arquivo/imagem/áudio (type, url, filename, size)
MessageActionAçã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".