NeboAI
NeboAI
Começar

Crie apps para o Nebo

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

Visão geral

O que é o Nebo

O Nebo é um assistente pessoal de IA para computador — um funcionário de IA sempre ativo que gere a sua vida digital. Pense no Nebo como pensa num smartphone: uma plataforma poderosa que se torna transformadora graças às suas apps.

Por si só, o Nebo é um funcionário de IA competente, com memória, agendamento, navegação na web, gestão de ficheiros e acesso à shell. Mas o verdadeiro salto vem das apps. Tal como o poder de um smartphone vem do seu ecossistema de apps, o poder do Nebo vem das apps que alargam o que ele consegue fazer.

O que são as apps

As apps do Nebo são unidades autónomas e pré-compiladas de funcionalidades incríveis. Cada app dá ao Nebo um novo superpoder — gestão de calendário, triagem de email, acompanhamento de projetos, domótica, análise financeira — tudo o que um programador conseguir imaginar.

As apps dão um poder incrível de forma muito segura. Cada app corre numa sandbox com permissões negadas por predefinição. Só pode aceder ao que o seu manifesto declara e o utilizador aprova.

A interface é 100% conversacional. Os utilizadores não interagem com as apps através de ecrãs ou painéis separados. Falam com o Nebo, e o Nebo usa as ferramentas da app para fazer as coisas. «O que tenho no calendário amanhã?» — o Nebo chama a app de calendário. «Marca uma reunião com a Sara às 3 da tarde» — o Nebo chama a app de calendário. O utilizador nunca sai da conversa.

As apps podem, opcionalmente, oferecer uma interface de definições — um painel de configuração que abre na janela de navegador integrada do Nebo. É aqui que os utilizadores introduzem chaves de API, ativam funcionalidades e configuram a app. A interface de definições é gerada a partir da matriz settings do manifesto (o Nebo apresenta o formulário automaticamente), ou a app pode fornecer a sua própria interface totalmente personalizada através da capacidade ui.

As apps substituem e alargam as capacidades integradas do Nebo. O Nebo vem com ferramentas básicas da plataforma (acesso ao calendário local, capturas de ecrã, etc.). Quando instala uma app de calendário, ela substitui a ferramenta de calendário integrada e torna-se um superconjunto — local + nuvem + agregação + verificação de disponibilidade.

Política de apenas compilados

O Nebo aplica uma política rigorosa de apenas binários compilados. Todas as apps têm de ser executáveis nativos compilados.

EstadoLinguagens
SuportadasGo (recomendado), Rust, C/C++, Zig
RejeitadasPython, Node.js, Ruby, Java, .NET, scripts de shell

Justificação:

  • Prevenção da automodificação da IA — Um funcionário de IA com acesso à shell poderia alterar o comportamento de um script interpretado em tempo de execução. Os 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 alterado 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 fiável.

Início rápido

Instalar o SDK

Os SDKs oficiais tratam de toda a configuração do servidor gRPC, do tratamento de sinais e da ponte de protocolos. Só tem de implementar as interfaces de handler.

Go (recomendado):

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

Rust (brevemente):

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

C/C++ (brevemente):

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

Estrutura de diretórios da app

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

Lista de verificação de uma app mínima

  1. Crie o manifest.json com id, name, version, provides
  2. Escreva um TOOL.md que descreva como o funcionário de IA deve usar a 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. Registe 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 deteta-o e inicia-o automaticamente

Configuração

manifest.json

Todas as apps precisam 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 invertido (por exemplo, com.mycompany.myapp)
nameNome legível
versionCadeia semver
providesPelo menos uma capacidade (ver abaixo)

Campos opcionais:

CampoPredefiniçãoDescrição
runtime"local""local" ou "remote"
protocol"grpc"Só é suportado "grpc"
permissions[]Aquilo a que a app precisa de aceder
description""Apresentado na interface
settings[]Definições configuráveis (apresentadas na interface de Definições)
oauth[]Requisitos de fornecedor OAuth (ver a secção OAuth abaixo)

Capacidades

Declare o que a sua app fornece:

CapacidadeServiço gRPCDescrição
gatewayGatewayServiceEncaminhamento de modelos LLM
tool:<name>ToolServiceUma ferramenta com nome 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 do navegador

Uma app pode fornecer várias capacidades. Por exemplo, uma app pode fornecer uma ferramenta e um painel de interface.

Permissões

As permissões controlam aquilo a que a app pode aceder. Tudo é negado por predefinição — se não estiver declarado, a app não o pode usar.

PrefixoExemplosDescrição
network:network:outbound, network:*Acesso à rede
filesystem:filesystem:read, filesystem:writeAcesso ao sistema de ficheiros
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 utilizador nos pedidos
schedule:schedule:createGestão de tarefas cron
database:database:queryAcesso à base 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 conselheiros
mcp:mcp:connectAcesso a servidores MCP
voice:voice:recordAcesso a voz/áudio
browser:browser:navigateAutomação do navegador
oauth:oauth:google, oauth:*Acesso a tokens OAuth
settings:settings:readAcesso às definições
capability:capability:registerRegisto de capacidades

São suportadas permissões com caráter universal: network:* corresponde a qualquer verificação de permissão network:.

Definições

As definições aparecem na interface do Nebo, no painel de definições da app. O Nebo guarda-as na base de dados e envia-as para a sua app através do RPC Configure sempre que mudam.

O esquema das suas definições é incluído na listagem da app na loja da NeboAI. As apps com definições obrigatórias por configurar mostram um selo «Precisa de configuração» na interface.

TipoDescrição
textCampo de texto de uma linha
passwordCampo de texto oculto
toggleInterruptor booleano ligado/desligado
selectLista pendente 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

As apps podem declarar requisitos de fornecedor OAuth. O broker OAuth do Nebo trata de todo o fluxo — as apps recebem os tokens automaticamente através do RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
CampoDescrição
providerFornecedor OAuth: "google", "microsoft", "github"
scopesMatriz dos âmbitos OAuth de que a app precisa

Quando o utilizador instala a app, o Nebo pede-lhe que autorize os âmbitos OAuth necessários. A app recebe tokens atualizados através do RPC Configure sem ter de tratar ela própria do fluxo OAuth.

Variáveis de ambiente

O processo da sua app recebe um ambiente higienizado. Todos os segredos são removidos. Recebe:

VariávelValor
NEBO_APP_DIRDiretório de instalação da app
NEBO_APP_SOCKCaminho para o socket Unix a criar
NEBO_APP_IDID da app indicado no manifesto
NEBO_APP_NAMENome da app indicado no manifesto
NEBO_APP_VERSIONVersão da app indicada no manifesto
NEBO_APP_DATACaminho para o diretório data/ da app
PATHPATH do sistema (transmitido tal como está)
HOMEDiretório pessoal do utilizador (transmitido tal como está)
TMPDIRDiretório temporário (transmitido tal como está)

Importante: O seu binário tem de criar um servidor gRPC à escuta no socket Unix em NEBO_APP_SOCK. O Nebo espera até 10 segundos que este socket apareça.

Sequência de arranque da app

  1. O Nebo lê o manifest.json e valida-o
  2. Procura o executável binary ou app no diretório da app
  3. Verifica se existe o marcador .quarantined (recusa iniciar apps em quarentena)
  4. Verificação de revogação (apenas apps distribuídas pela NeboAI)
  5. Verificação da assinatura (apenas apps distribuídas pela NeboAI; ignorada em desenvolvimento)
  6. Validação do binário (rejeita ligações simbólicas, scripts, ficheiros não executáveis e ficheiros demasiado grandes)
  7. Limpa o socket antigo da execução anterior
  8. Cria o diretório data/ para armazenamento isolado
  9. Configura ficheiros de registo por app (logs/stdout.log, logs/stderr.log)
  10. Inicia o binário com um ambiente higienizado e isolamento do grupo de processos
  11. Espera que o socket Unix apareça (backoff exponencial, máximo de 10 segundos)
  12. Liga-se por gRPC através do socket Unix
  13. Cria clientes gRPC específicos de cada capacidade com base em provides
  14. Executa a verificação de estado
  15. Regista as capacidades junto do funcionário de IA (ferramentas, gateway, comm, etc.)

Apps de ferramentas

Declare "provides": ["tool:my_tool_name"] no seu manifesto.

O padrão STRAP

Todas as apps de ferramentas do Nebo têm de usar o STRAP (Single Tool Resource Action Pattern) no seu esquema e no encaminhamento da execução. É o mesmo padrão que o Nebo usa internamente para reunir 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 registar várias ferramentas (get_events, check_availability, suggest_slots), registe UMA ferramenta com campos action (e, opcionalmente, resource) que encaminham para o handler certo.

Exemplo com um só recurso (calendário):

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 (gestor 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. Inclua sempre um campo action como enum de cadeia obrigatório
  2. Adicione um campo resource (enum de cadeia obrigatório) apenas se a sua ferramenta gerir 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

Porque é que o STRAP importa:

  • Os LLMs aprendem o padrão de encaminhamento por action uma vez e generalizam-no a 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 registos de ferramentas
  • Funciona da mesma forma com modelos alojados 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": []
}

Compilar e instalar:

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"].

As apps de canal ligam plataformas de mensagens externas (Telegram, Discord, Slack, etc.) ao funcionário de IA do Nebo. Quando um utilizador envia uma mensagem na plataforma externa, a sua app transmite-a ao Nebo através de Receive. Quando o funcionário de IA quer responder, o Nebo chama o Send da sua 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 das definições da sua app
  3. O Nebo abre um stream Receive() — a sua app envia as mensagens recebidas sempre que um utilizador escreve ao bot
  4. As mensagens recebidas são encaminhadas 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. Ao encerrar, 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 no tempo
channel_id{type}:{platform_id}Identificador de canal encaminhável
senderobjectIdentidade do bot — nome, função, botId
textstringCorpo da mensagem
attachmentsarrayFicheiros, imagens, áudio
reply_toUUID v7ID da mensagem principal, para conversas em fio
actionsarrayBotões/teclados interativos
platform_databytesDados opacos transmitidos tal como estão, para funcionalidades específicas da plataforma
timestampISO 8601Definido pelo editor

Design em duas camadas: Os campos comuns (text, attachments, reply_to, actions) cobrem 90% das mensagens iniciadas por funcionários. As funcionalidades específicas da plataforma vão em platform_data — o seu plugin converte-as de e para o formato nativo da plataforma.

Streams de conversa

As mensagens de canal são encaminhadas por streams de conversa separados para cada canal, para garantir o 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 de 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 Comm

Declare "provides": ["comm"] e "permissions": ["comm:*"]. As apps comm 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 suas capacidades
  • Subscribe/Unsubscribe gerem as subscrições de tópicos
  • Receive transmite as mensagens recebidas (streaming do servidor, tal como nos canais)
  • Só pode estar ativa uma app comm de cada vez

App de gateway

Uma app de gateway encaminha pedidos 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"Fragmento de textoToken de texto em streaming
"tool_call"JSONO modelo quer chamar uma ferramenta
"thinking"Fragmento de textoPensamento/raciocínio alargado
"error"Mensagem de erroAlgo correu mal
"done"VazioO stream terminou

App de interface

Uma app de interface fornece uma interface de configuração personalizada que abre na janela de navegador integrada do Nebo. Declare "provides": ["ui"]. Ao contrário do formulário de definições automático (que o Nebo gera a partir do settings do seu manifesto), uma app de interface serve o seu próprio frontend completo em HTML/CSS/JS.

A sua app inclui um diretório ui/ com recursos web estáticos (HTML, CSS, JS — normalmente uma SPA com index.html). O Nebo serve estes ficheiros diretamente e encaminha as chamadas à API para a sua app por gRPC.

CaminhoMecanismoFinalidade
GET /api/v1/apps/{id}/ui/*Servidor de ficheiros estáticosServe ficheiros do seu diretório ui/ (com recurso a index.html para a SPA)
ANY /api/v1/apps/{id}/api/*Proxy gRPCEncaminha os pedidos HTTP para o UIService.HandleRequest() da sua app

O SDK envolve um net/http.ServeMux padrão, por isso escreve handlers HTTP normais em Go — o SDK trata automaticamente da ponte gRPC.

Exemplo em Go — Interface de painel:

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

O seu ui/index.html faria chamadas fetch para /api/v1/apps/com.example.dashboard/api/status, que são encaminhadas para o seu handler mux.

App de agendamento

Uma app de agendamento substitui o agendador cron integrado do Nebo. Declare "provides": ["schedule"] e "permissions": ["schedule:create"].

Quando a sua app de agendamento arranca, o Nebo encaminha todo o agendamento pela sua app em vez do motor cron predefinido. Se a sua app falhar, o Nebo volta automaticamente ao motor integrado.

  • A sua app é dona do estado dos agendamentos — o Nebo não guarda agendamentos na sua própria base de dados enquanto houver uma app de agendamento ativa
  • CRUD padrão: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers é um RPC com streaming do servidor — a sua app envia uma mensagem de disparo sempre que um agendamento é acionado
  • Só pode estar ativa uma app de agendamento de cada vez

Apps com várias capacidades

Uma app pode fornecer várias capacidades. Por exemplo, uma app de painel 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 através da NeboAI, empacote a sua app como um ficheiro .napp (um arquivo tar.gz):

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

Ficheiros obrigatórios:

FicheiroTamanho máximoDescrição
manifest.json1 MBMetadados da 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 durante a extração:

  • Sem travessia de caminhos (../ é rejeitado)
  • Sem ligações simbólicas (rejeitadas)
  • Sem caminhos absolutos (rejeitados)
  • Só são aceites nomes de ficheiro da lista permitida

Assinaturas

A NeboAI assina as 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 configurado), a verificação da assinatura é totalmente ignorada. Não precisa de signatures.json para o desenvolvimento local.

Publicação

Quando a sua app funcionar localmente, publique-a através da NeboAI para a distribuir a todos os utilizadores do Nebo.

Configuração da conta de programador

  1. Registe uma conta NeboAI em POST /api/v1/owners/register
  2. Inicie sessão para obter um token JWT: POST /api/v1/owners/login
  3. Crie uma conta de programador: POST /api/v1/developer/accounts

Fluxo de submissão

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

Passo 1: Criar a 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: Carregar os binários das plataformas

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"

Carregue um binário por plataforma: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Passo 3: Submeter para revisão

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

Processo de revisão

  1. Análise automática — os binários são analisados pelo VirusTotal
  2. Revisão pela administração — a equipa da NeboAI revê os metadados, o manifesto e os resultados da análise
  3. Se for aprovada — a NeboAI assina a app com Ed25519 e publica-a
  4. Se for rejeitada — recebe o motivo e pode corrigir e voltar a submeter

Tempo de revisão previsto: <24 horas.

Publicar atualizações

  1. Atualize a versão da app: PUT /api/v1/developer/apps/{id} com a nova versão
  2. Carregue novos binários para cada plataforma
  3. Submeta novamente para revisão

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 da app
visibilitypublic ou private
descriptionPode ser mais longa e mais rica do que a descrição do manifesto

Fluxo de desenvolvimento

Desenvolvimento local

Não é preciso empacotar para o desenvolvimento local:

  1. Crie o diretório da sua app:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Escreva o seu manifest.json e o código
  3. Compile o seu binário:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. O Nebo deteta automaticamente o novo diretório (ou reinicie o Nebo)
  5. Depois de alterar o código, volte a compilar o binário — o observador de ficheiros reinicia a app

Ver os registos

O stdout/stderr da app é guardado em ficheiros de registo 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 quaisquer ficheiros que a sua app precise de manter. Este diretório sobrevive às atualizações da app e à quarentena.

Dicas de depuração

  • Se a sua app não arrancar, verifique se há erros em logs/stderr.log
  • Confirme que o binário é executável (chmod +x binary)
  • Confirme que está à escuta no caminho do socket Unix indicado em NEBO_APP_SOCK
  • O socket tem de estar pronto nos 10 segundos seguintes ao arranque
  • Use NEBO_APP_DATA para o armazenamento, e não caminhos fixos no código
  • Escreva no stderr para registos de depuração (guardados 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 as skills

As skills são conjuntos de instruções que moldam o comportamento do Nebo durante uma conversa. Quando uma skill está ativa, o seu conteúdo é injetado diretamente no prompt de sistema — orientando o tom, a metodologia, os conhecimentos especializados e o uso de ferramentas do funcionário de IA nessa sessão.

As 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 ficheiro SKILL.md num diretório. Mais nada.

As skills são contextuais e temporárias. Ativam-se quando são relevantes (por correspondência de gatilhos ou carregamento manual), mantêm-se durante algumas interações e expiram quando deixam de ser necessárias. Assim, o contexto do funcionário de IA mantém-se leve — no prompt só está a orientação que importa naquele momento.

As skills complementam as apps. As apps fornecem capacidades executáveis (ferramentas, canais, gateways). As skills fornecem orientação de orquestração — como usar bem essas ferramentas. Uma app de calendário dá ao Nebo a capacidade de ler e escrever eventos. Uma skill de «preparação de reuniões» diz ao Nebo como se preparar para reuniões usando em conjunto essa app de calendário, o email e a pesquisa na web.

Skills vs. apps

SkillsApps
FormatoMarkdown (SKILL.md)Binário compilado (.napp)
ExecuçãoInjetadas no prompt de sistemaProcesso em sandbox através de gRPC
FornecemOrientação de comportamento, metodologiaFerramentas, canais, painéis de interface
DuraçãoLimitadas à sessão, expiram por TTLSempre em execução
CriaçãoEscrever um ficheiro markdownEscrever, compilar, assinar, empacotar
SegurançaNão precisam de permissõesSandbox com tudo negado por predefinição

Início rápido

Crie um diretório na pasta de skills do Nebo com um ficheiro 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 vigia o diretório de skills com fsnotify. A sua skill fica disponível de imediato — sem reiniciar. Diga algo que corresponda a um gatilho e ela ativa-se automaticamente.

Ou peça diretamente ao Nebo: «Cria uma skill para escrever artigos de blogue» — o Nebo escreve o ficheiro SKILL.md por si.

Formato do SKILL.md

Cada skill é um único ficheiro SKILL.md com duas partes: frontmatter YAML entre marcadores --- e um corpo em markdown (as instruções propriamente ditas, injetadas no prompt de sistema).

CampoObrigatórioPredefiniçãoDescrição
nameSim—Identificador único (torna-se o slug)
descriptionSim—Descrição de uma linha apresentada no catálogo de skills
versionNão"1.0.0"Semver para acompanhar atualizações
authorNão—Autor da skill
priorityNão0Mais alto = corresponde primeiro (100+ para substituições críticas)
max_turnsNão4Interações sem atividade antes da expiração automática
triggersNão[]Expressões que ativam esta skill automaticamente (correspondência de subcadeia, sem distinguir maiúsculas)
toolsNão[]Ferramentas que esta skill espera usar (informativo)
dependenciesNão[]Outras skills que têm de estar instaladas
tagsNão[]Para categorização e descoberta
platformNão[]Plataformas suportadas: macos, linux, windows (vazio = todas)

Como se ativam as skills

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 utilizador envia uma mensagem, o Nebo procura correspondências de gatilhos em todas as skills registadas. 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")

Isto devolve o modelo SKILL.md completo como resultado da ferramenta, regista a invocação e volta a injetar o modelo no prompt de sistema nas interações seguintes.

TTL e expiração:

  • Skills ativadas automaticamente: 4 interações sem atividade (configurável com max_turns)
  • Skills carregadas manualmente: 6 interações sem atividade
  • Voltar a invocar reinicia o temporizador
  • Limite máximo: 4 skills ativas por sessão
  • Orçamento de tokens: o conteúdo combinado das skills ativas está limitado a 16,000 carateres

Gerir skills

O funcionário de IA pode gerir skills através da 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: "...")
deleteEliminar uma skill do discoskill(name: "my-skill", action: "delete")

Escrever boas skills

Um bom modelo de skill tem:

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

Skills incluídas

O Nebo vem com skills incluídas para os casos de uso mais comuns:

SkillPrioridadeDescrição
onboarding100Boas-vindas a novos utilizadores e recolha do perfil
best-friend50Skill de personalidade — descontraída, leal, sem rodeios
debugging25Metodologia de depuração sistemática
api-design15Boas práticas de design de APIs RESTful
code-review10Revisão de código estruturada com níveis de gravidade
database-expert10Design de bases de dados, consultas, otimização
git-workflow10Ramificações Git, commits, fluxos de PR
security-audit10Análise de segurança e deteção de vulnerabilidades

Servem tanto de predefinições úteis como de implementações de referência para criar as suas próprias skills.

Referência

Ficheiros proto

Os ficheiros proto ficam em proto/apps/v0/. Os SDKs incluem código pré-gerado, por isso não precisa do protoc no desenvolvimento normal.

FicheiroServiç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

Todos os serviços incluem os RPCs HealthCheck e Configure. O SDK trata de ambos 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 conversas em fio
InboundMessageEnvelope de mensagem recebida com todos os campos comuns + timestamp
MessageSenderIdentidade do bot (name, role, botId) — enriquecida pelo broker
AttachmentAnexo de ficheiro/imagem/áudio (type, url, filename, size)
MessageActionAção de botão/teclado interativo (label, callback_id)

Identidade e funções dos bots

Os bots do Nebo têm um modelo de identidade com três eixos:

  • creature — O que o bot é (arquétipo): «Estratega de raciocínio rápido», «Investigador meticuloso»
  • role — Como se relaciona com o utilizador (relação): «Amigo», «COO», «Mentor»
  • vibe — A sua energia (estilo de comunicação): «Descontraído mas com opinião», «Caloroso e encorajador»

Quando o seu plugin de canal recebe uma mensagem a enviar, o campo sender contém o name e o role do bot. Use-os para formatar o nome apresentado na sua plataforma. A função não é um cargo — descreve uma relação. «Amigo», «Filho» e «Mentor» são funções válidas, tal como «COO» e «DevLead».