개요
Nebo란
Nebo는 개인용 데스크톱 AI 어시스턴트로, 디지털 생활을 관리해 주는 항상 실행 중인 AI 직원입니다. 스마트폰을 떠올려 보세요. 앱을 통해 완전히 새로워지는 강력한 플랫폼, Nebo도 마찬가지입니다.
Nebo는 그 자체만으로도 메모리, 일정 관리, 웹 탐색, 파일 관리, 셸 접근 기능을 갖춘 유능한 AI 직원입니다. 하지만 진짜 잠재력은 앱에서 나옵니다. 스마트폰의 힘이 앱 생태계에서 나오듯, Nebo의 힘도 Nebo가 할 수 있는 일을 넓혀 주는 앱에서 나옵니다.
앱이란
Nebo 앱은 놀라운 기능을 담은 독립형 사전 컴파일 단위입니다. 각 앱은 Nebo에 새로운 초능력을 더합니다. 캘린더 관리, 이메일 분류, 프로젝트 추적, 홈 자동화, 재무 분석 등 개발자가 상상하는 무엇이든 가능합니다.
앱은 매우 안전한 방식으로 놀라운 능력을 제공합니다. 모든 앱은 기본 거부 권한이 적용된 샌드박스에서 실행됩니다. 매니페스트에 선언되고 사용자가 승인한 항목에만 접근할 수 있습니다.
인터페이스는 100% 대화형입니다. 사용자는 별도의 화면이나 대시보드로 앱을 다루지 않습니다. Nebo와 대화하면 Nebo가 앱의 도구를 사용해 일을 처리합니다. "내일 일정이 뭐야?"라고 물으면 Nebo가 캘린더 앱을 호출합니다. "오후 3시에 Sarah와 회의 잡아 줘"라고 하면 Nebo가 캘린더 앱을 호출합니다. 사용자는 대화를 떠날 필요가 없습니다.
앱은 선택적으로 설정 UI를 제공할 수 있습니다. Nebo의 내장 브라우저 창에서 열리는 구성 패널로, 사용자가 API 키를 입력하고 기능을 켜고 끄며 앱을 구성하는 곳입니다. 설정 UI는 매니페스트의 settings 배열로 구동되며(Nebo가 양식을 자동으로 렌더링), 앱이 ui 기능을 통해 완전한 자체 UI를 제공할 수도 있습니다.
앱은 Nebo의 기본 기능을 대체하고 확장합니다. Nebo에는 기본 플랫폼 도구(로컬 캘린더 접근, 스크린샷 등)가 포함되어 있습니다. 캘린더 앱을 설치하면 기본 캘린더 도구를 대체하는 상위 집합이 됩니다. 로컬, 클라우드, 통합, 가용 시간 확인까지 모두 처리합니다.
컴파일 전용 정책
Nebo는 엄격한 컴파일 전용 바이너리 정책을 적용합니다. 모든 앱은 네이티브로 컴파일된 실행 파일이어야 합니다.
| 상태 | 언어 |
|---|---|
| 지원 | Go(권장), Rust, C/C++, Zig |
| 거부 | Python, Node.js, Ruby, Java, .NET, 셸 스크립트 |
이유:
- AI의 자기 수정 방지 — 셸 접근 권한이 있는 AI 직원은 실행 중에 인터프리터 스크립트의 동작을 바꿀 수 있습니다. 컴파일된 바이너리는 서명 후 변경할 수 없습니다.
- 서명 무결성 — Ed25519 서명은 바이너리의 원시 바이트 전체를 대상으로 합니다. 서명된 바이너리는 서명을 무효화하지 않고는 수정할 수 없습니다.
- 샌드박스 적용 — 바이너리 형식 검증(ELF/Mach-O/PE 매직 바이트)은 빠르고 신뢰할 수 있는 관문입니다.
빠른 시작
SDK 설치
공식 SDK가 gRPC 서버 설정, 시그널 처리, 프로토콜 브리징을 모두 처리합니다. 핸들러 인터페이스만 구현하면 됩니다.
Go(권장):
go get github.com/neboloop/nebo-sdk-go Rust(곧 제공 예정):
# Coming soon
[dependencies]
nebo-sdk = "0.1" C/C++(곧 제공 예정):
# Coming soon — Add as a CMake subdirectory or copy headers from sdk/c/include/ 앱 디렉터리 구조
앱은 Nebo 데이터 디렉터리의 apps/ 하위 디렉터리에 위치합니다.
~/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) 최소 앱 체크리스트
id,name,version,provides가 포함된manifest.json만들기- AI 직원이 도구를 어떻게 사용해야 하는지 설명하는
TOOL.md작성하기 - SDK 설치하기(
go get github.com/neboloop/nebo-sdk-go) - 기능에 맞는 핸들러 인터페이스 구현하기(
ToolHandler,ChannelHandler등) - 핸들러를 등록하고
app.Run()호출하기 - 네이티브 바이너리 빌드하기(
go build -o binary .) - 바이너리, manifest.json, TOOL.md를
apps/<your-app-id>/디렉터리에 넣기 - Nebo가 자동으로 찾아 실행합니다
구성
manifest.json
모든 앱에는 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
}
]
} 필수 필드:
| 필드 | 설명 |
|---|---|
id | 역도메인 식별자(예: com.mycompany.myapp) |
name | 사람이 읽을 수 있는 이름 |
version | Semver 문자열 |
provides | 하나 이상의 기능(아래 참조) |
선택 필드:
| 필드 | 기본값 | 설명 |
|---|---|---|
runtime | "local" | "local" 또는 "remote" |
protocol | "grpc" | "grpc"만 지원됩니다 |
permissions | [] | 앱이 접근해야 하는 항목 |
description | "" | UI에 표시됩니다 |
settings | [] | 구성 가능한 설정(설정 UI에 렌더링됨) |
oauth | [] | OAuth 공급자 요구 사항(아래 OAuth 섹션 참조) |
기능
앱이 제공하는 기능을 선언하세요.
| 기능 | gRPC 서비스 | 설명 |
|---|---|---|
gateway | GatewayService | LLM 모델 라우팅 |
tool:<name> | ToolService | AI 직원을 위한 이름 있는 도구 |
channel:<name> | ChannelService | 메시징 채널 |
comm | CommService | AI 직원 간 통신 |
ui | UIService | HTTP 프록시를 사용하는 사용자 지정 UI |
schedule | ScheduleService | 사용자 지정 일정 관리 |
vision | ToolService | 비전 처리 |
browser | ToolService | 브라우저 자동화 |
앱은 여러 기능을 제공할 수 있습니다. 예를 들어 하나의 앱이 도구와 UI 패널을 함께 제공할 수 있습니다.
권한
권한은 앱이 접근할 수 있는 항목을 제어합니다. 기본값은 거부입니다. 선언하지 않은 항목은 앱이 사용할 수 없습니다.
| 접두사 | 예시 | 설명 |
|---|---|---|
network: | network:outbound, network:* | 네트워크 접근 |
filesystem: | filesystem:read, filesystem:write | 파일 시스템 접근 |
memory: | memory:read, memory:write | AI 직원 메모리 접근 |
session: | session:read | 대화 세션 |
tool: | tool:shell, tool:file | 다른 도구 사용 |
shell: | shell:exec | 셸 명령 실행 |
channel: | channel:send, channel:* | 채널 작업 |
comm: | comm:send, comm:* | AI 직원 간 통신 |
model: | model:chat | AI 모델 접근 |
user: | user:token | 요청에서 사용자 JWT 수신 |
schedule: | schedule:create | 크론 작업 관리 |
database: | database:query | 데이터베이스 접근 |
storage: | storage:read, storage:write | 영구 저장소 |
context: | context:read | AI 직원 컨텍스트 접근 |
subagent: | subagent:spawn | 하위 에이전트 작업 |
lane: | lane:enqueue | 레인 작업 |
notification: | notification:send | 푸시 알림 |
embedding: | embedding:search | 벡터 임베딩 접근 |
skill: | skill:invoke | 스킬 호출 |
advisor: | advisor:consult | 어드바이저 시스템 접근 |
mcp: | mcp:connect | MCP 서버 접근 |
voice: | voice:record | 음성/오디오 접근 |
browser: | browser:navigate | 브라우저 자동화 |
oauth: | oauth:google, oauth:* | OAuth 토큰 접근 |
settings: | settings:read | 설정 접근 |
capability: | capability:register | 기능 등록 |
와일드카드 권한을 지원합니다. network:*는 모든 network: 권한 검사와 일치합니다.
설정
설정은 Nebo UI의 앱 설정 패널에 표시됩니다. Nebo는 설정을 데이터베이스에 저장하고, 설정이 바뀌면 Configure RPC를 통해 앱에 전달합니다.
설정 스키마는 NeboAI 앱 스토어 목록에 포함됩니다. 필수 설정이 구성되지 않은 앱에는 UI에 "설정 필요" 배지가 표시됩니다.
| 유형 | 설명 |
|---|---|
text | 한 줄 텍스트 입력 |
password | 마스킹된 텍스트 입력 |
toggle | 켜기/끄기 스위치 |
select | 미리 정의된 옵션이 있는 드롭다운 |
number | 숫자 입력 |
url | 유효성 검사가 포함된 URL 입력 |
{
"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"}
]
} OAuth 요구 사항
앱은 OAuth 공급자 요구 사항을 선언할 수 있습니다. Nebo의 OAuth 브로커가 전체 흐름을 처리하며, 앱은 Configure RPC를 통해 토큰을 자동으로 받습니다.
{
"oauth": [
{
"provider": "google",
"scopes": ["https://www.googleapis.com/auth/calendar"]
}
]
} | 필드 | 설명 |
|---|---|
provider | OAuth 공급자: "google", "microsoft", "github" |
scopes | 앱에 필요한 OAuth 범위 배열 |
사용자가 앱을 설치하면 Nebo가 필요한 OAuth 범위를 승인하도록 안내합니다. 앱은 OAuth 흐름을 직접 처리하지 않고도 Configure RPC를 통해 갱신된 토큰을 받습니다.
환경 변수
앱 프로세스는 정리된 환경을 받습니다. 모든 비밀 값은 제거됩니다. 제공되는 항목은 다음과 같습니다.
| 변수 | 값 |
|---|---|
NEBO_APP_DIR | 앱 설치 디렉터리 |
NEBO_APP_SOCK | 생성할 Unix 소켓 경로 |
NEBO_APP_ID | 매니페스트의 앱 ID |
NEBO_APP_NAME | 매니페스트의 앱 이름 |
NEBO_APP_VERSION | 매니페스트의 앱 버전 |
NEBO_APP_DATA | 앱의 data/ 디렉터리 경로 |
PATH | 시스템 PATH(그대로 전달) |
HOME | 사용자 홈 디렉터리(그대로 전달) |
TMPDIR | 임시 디렉터리(그대로 전달) |
중요: 바이너리는 NEBO_APP_SOCK의 Unix 소켓에서 수신 대기하는 gRPC 서버를 만들어야 합니다. Nebo는 이 소켓이 나타나기를 최대 10초 동안 기다립니다.
앱 실행 순서
- Nebo가
manifest.json을 읽고 검증합니다 - 앱 디렉터리에서
binary또는app실행 파일을 찾습니다 .quarantined표시가 있는지 확인합니다(격리된 앱은 실행하지 않음)- 폐기 여부 확인(NeboAI에서 배포한 앱만 해당)
- 서명 검증(NeboAI에서 배포한 앱만 해당, 개발 모드에서는 생략)
- 바이너리 검증(심볼릭 링크, 스크립트, 실행 불가 파일, 크기 초과 파일 거부)
- 이전 실행에서 남은 오래된 소켓을 정리합니다
- 샌드박스 저장소용
data/디렉터리를 만듭니다 - 앱별 로그 파일을 설정합니다(
logs/stdout.log,logs/stderr.log) - 정리된 환경과 프로세스 그룹 격리 상태로 바이너리를 시작합니다
- Unix 소켓이 나타날 때까지 기다립니다(지수 백오프, 최대 10초)
- Unix 소켓을 통해 gRPC로 연결합니다
provides를 기반으로 기능별 gRPC 클라이언트를 만듭니다- 상태 확인을 실행합니다
- AI 직원에 기능을 등록합니다(도구, 게이트웨이, 통신 등)
도구 앱
매니페스트에 "provides": ["tool:my_tool_name"]을 선언하세요.
STRAP 패턴
모든 Nebo 도구 앱은 스키마와 실행 라우팅에 STRAP(Single Tool Resource Action Pattern)을 반드시 사용해야 합니다. Nebo가 내부적으로 35개 이상의 개별 도구를 4개의 도메인 도구로 통합할 때 쓰는 것과 같은 패턴으로, LLM 컨텍스트 부담을 약 80% 줄여 줍니다.
핵심 아이디어: 여러 도구(get_events, check_availability, suggest_slots)를 등록하는 대신, 알맞은 핸들러로 라우팅하는 action 필드(선택적으로 resource 필드)를 가진 도구 하나만 등록합니다.
단일 리소스 예시(캘린더):
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") 다중 리소스 예시(프로젝트 관리자):
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") 스키마 규칙:
- 항상
action필드를 필수 문자열 enum으로 포함하세요 - 도구가 서로 다른 여러 리소스 유형을 관리하는 경우에만
resource필드(필수 문자열 enum)를 추가하세요 - 나머지 필드는 모두 작업별 매개변수입니다
actionenum 설명에는 사용 가능한 모든 작업을 나열해야 합니다
STRAP이 중요한 이유:
- LLM은
action라우팅 패턴을 한 번 익히면 모든 작업에 일반화합니다 - 도구 정의는 컨텍스트의 약 6%를 차지하며, STRAP은 이를 80% 줄입니다
- 새 작업은 새 도구 등록이 아니라 enum 항목 추가만으로 충분합니다
- 호스팅 모델과 로컬 모델에서 똑같이 작동합니다
Go 예시 — 계산기 도구
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": []
} 빌드 및 설치:
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/ 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(())
} 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;
} 채널 앱
"provides": ["channel:my_channel"]과 "permissions": ["channel:send"]를 선언하세요.
채널 앱은 외부 메시징 플랫폼(Telegram, Discord, Slack 등)을 Nebo의 AI 직원과 연결합니다. 사용자가 외부 플랫폼에서 메시지를 보내면 앱이 Receive를 통해 Nebo로 스트리밍합니다. AI 직원이 답장하려 할 때는 Nebo가 앱의 Send를 호출합니다.
작동 방식
- Nebo가
ID()를 호출해 채널의 고유 식별자를 가져옵니다 - Nebo가 앱 설정의 구성 값으로
Connect()를 호출합니다 - Nebo가
Receive()스트림을 엽니다. 사용자가 봇에게 메시지를 보낼 때마다 앱이 수신 메시지를 전송합니다 - 수신 메시지는 AI 직원의 기본 대화 레인으로 라우팅됩니다
- AI 직원이 메시지를 보내려 하면 Nebo가 v1 메시지 봉투와 함께
Send()를 호출합니다 - 종료 시 Nebo가
Disconnect()를 호출합니다
v1 메시지 봉투
모든 채널 메시지는 수신과 발신 모두 공통 메시지 봉투를 사용합니다.
{
"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"
} | 필드 | 유형 | 설명 |
|---|---|---|
message_id | UUID v7 | 시간순 고유 ID |
channel_id | {type}:{platform_id} | 라우팅 가능한 채널 식별자 |
sender | object | 봇 정체성 — name, role, botId |
text | string | 메시지 본문 |
attachments | array | 파일, 이미지, 오디오 |
reply_to | UUID v7 | 스레드용 상위 메시지 ID |
actions | array | 대화형 버튼/키보드 |
platform_data | bytes | 플랫폼별 기능을 위한 불투명 전달 데이터 |
timestamp | ISO 8601 | 게시자가 설정합니다 |
2계층 설계: 공통 필드(text, attachments, reply_to, actions)가 직원이 시작하는 메시징의 90%를 처리합니다. 플랫폼별 기능은 platform_data에 들어가며, 플러그인이 이를 네이티브 플랫폼 형식과 서로 변환합니다.
대화 스트림
채널 메시지는 격리를 위해 채널별 대화 스트림으로 라우팅됩니다.
neboai/bot/{botID}/channels/{channelType}/inbound # messages from users → agent
neboai/bot/{botID}/channels/{channelType}/outbound # messages from agent → channel Go 예시 — 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
}
]
} 추가 기능
통신 앱
"provides": ["comm"]과 "permissions": ["comm:*"]를 선언하세요. 통신 앱은 AI 직원 간의 통신을 가능하게 합니다.
| 필드 | 설명 |
|---|---|
from | 보낸 직원 ID |
to | 받는 직원 ID |
topic | 메시지 토픽/채널 |
type | "message", "mention", "proposal", "command", "info", "task" |
content | 메시지 본문 |
주요 동작:
Register는 이 AI 직원을 기능과 함께 네트워크에 알립니다Subscribe/Unsubscribe는 토픽 구독을 관리합니다Receive는 수신 메시지를 스트리밍합니다(채널과 동일한 서버 스트리밍)- 한 번에 하나의 통신 앱만 활성화할 수 있습니다
게이트웨이 앱
게이트웨이 앱은 LLM 요청을 모델로 라우팅합니다. "provides": ["gateway"]와 "permissions": ["network:outbound", "user:token"]을 선언하세요.
GatewayRequest에는 메시지, 도구, 시스템 프롬프트, 최대 토큰, temperature, 그리고 UserContext(user:token 권한이 부여된 경우 JWT 토큰)가 포함됩니다.
GatewayEvent 유형:
| 유형 | 내용 | 설명 |
|---|---|---|
"text" | 텍스트 청크 | 스트리밍 텍스트 토큰 |
"tool_call" | JSON | 모델이 도구를 호출하려고 합니다 |
"thinking" | 텍스트 청크 | 확장 사고/추론 |
"error" | 오류 메시지 | 문제가 발생했습니다 |
"done" | 비어 있음 | 스트림이 완료되었습니다 |
UI 앱
UI 앱은 Nebo의 내장 브라우저 창에서 열리는 사용자 지정 구성 인터페이스를 제공합니다. "provides": ["ui"]를 선언하세요. Nebo가 settings 매니페스트로 렌더링하는 자동 설정 양식과 달리, UI 앱은 자체 HTML/CSS/JS 프런트엔드 전체를 제공합니다.
앱에는 정적 웹 애셋(HTML, CSS, JS — 보통 index.html이 있는 SPA)이 담긴 ui/ 디렉터리가 포함됩니다. Nebo는 이 파일을 직접 제공하고 API 호출은 gRPC를 통해 앱으로 프록시합니다.
| 경로 | 메커니즘 | 목적 |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | 정적 파일 서버 | ui/ 디렉터리의 파일을 제공합니다(SPA 대체 경로는 index.html) |
ANY /api/v1/apps/{id}/api/* | gRPC 프록시 | HTTP 요청을 앱의 UIService.HandleRequest()로 프록시합니다 |
SDK가 표준 net/http.ServeMux를 감싸므로 일반적인 Go HTTP 핸들러를 작성하면 됩니다. gRPC 브리징은 SDK가 자동으로 처리합니다.
Go 예시 — 대시보드 UI:
package main
import (
"encoding/json"
"log"
"net/http"
nebo "github.com/neboloop/nebo-sdk-go"
)
type Dashboard struct {
mux *http.ServeMux
}
func NewDashboard() *Dashboard {
d := &Dashboard{mux: http.NewServeMux()}
d.mux.HandleFunc("GET /status", func(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
})
d.mux.HandleFunc("POST /action", func(w http.ResponseWriter, r *http.Request) {
var req map[string]string
json.NewDecoder(r.Body).Decode(&req)
json.NewEncoder(w).Encode(map[string]string{"result": "done"})
})
return d
}
func (d *Dashboard) Handler() *http.ServeMux { return d.mux }
func main() {
app, err := nebo.New()
if err != nil {
log.Fatal(err)
}
app.RegisterUI(NewDashboard())
log.Fatal(app.Run())
} ui/index.html에서 /api/v1/apps/com.example.dashboard/api/status로 fetch 호출을 하면 mux 핸들러로 프록시됩니다.
일정 앱
일정 앱은 Nebo의 기본 크론 스케줄러를 대체합니다. "provides": ["schedule"]과 "permissions": ["schedule:create"]를 선언하세요.
일정 앱이 실행되면 Nebo는 기본 크론 엔진 대신 앱을 통해 모든 일정을 처리합니다. 앱이 충돌하면 Nebo가 자동으로 기본 엔진으로 되돌아갑니다.
- 앱이 일정 상태를 소유합니다. 일정 앱이 활성화되어 있으면 Nebo는 자체 DB에 일정을 저장하지 않습니다
- 표준 CRUD:
Create,Get,List,Update,Delete,Enable,Disable Triggers는 서버 스트리밍 RPC입니다. 일정이 실행될 때마다 앱이 트리거 메시지를 보냅니다- 한 번에 하나의 일정 앱만 활성화할 수 있습니다
다중 기능 앱
앱은 여러 기능을 제공할 수 있습니다. 예를 들어 도구와 UI를 모두 갖춘 대시보드 앱은 다음과 같습니다.
{
"id": "com.example.dashboard",
"name": "Dashboard",
"version": "1.0.0",
"provides": ["tool:dashboard_query", "ui"],
"permissions": ["network:outbound"]
} app, _ := nebo.New()
app.RegisterTool(&dashboardTool{})
app.RegisterUI(&dashboardUI{})
log.Fatal(app.Run()) 패키징
.napp 형식
NeboAI를 통해 배포하려면 앱을 .napp 파일(tar.gz 아카이브)로 패키징하세요.
cd com.example.myapp/
tar -czf myapp-1.0.0.napp manifest.json binary signatures.json TOOL.md 필수 파일:
| 파일 | 최대 크기 | 설명 |
|---|---|---|
manifest.json | 1 MB | 앱 메타데이터 |
binary 또는 app | 500 MB | 실행 파일 |
signatures.json | 1 MB | Ed25519 서명 |
TOOL.md | 1 MB | AI 직원을 위한 도구 지침 |
압축 해제 시 보안 규칙:
- 경로 탐색 금지(
../거부) - 심볼릭 링크 금지(거부)
- 절대 경로 금지(거부)
- 허용 목록에 있는 파일 이름만 허용
서명
NeboAI는 Ed25519로 앱에 서명합니다. 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>"
} 개발 모드(NeboAI URL이 구성되지 않은 상태)에서는 서명 검증을 완전히 건너뜁니다. 로컬 개발에는 signatures.json이 필요하지 않습니다.
게시
앱이 로컬에서 잘 작동하면 NeboAI를 통해 게시해 모든 Nebo 사용자에게 배포하세요.
개발자 계정 설정
POST /api/v1/owners/register에서 NeboAI 계정을 등록합니다- 로그인해 JWT 토큰을 받습니다:
POST /api/v1/owners/login - 개발자 계정을 만듭니다:
POST /api/v1/developer/accounts
제출 흐름
draft → pending_review → [approved] → published
→ [rejected] → draft (fix and resubmit) 1단계: 앱 만들기
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"
}' 2단계: 플랫폼 바이너리 업로드
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" 플랫폼마다 바이너리를 하나씩 업로드하세요: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.
3단계: 검토 제출
curl -X POST https://neboai.com/api/v1/developer/apps/{id}/submit \
-H "Authorization: Bearer $TOKEN" 검토 과정
- 자동 검사 — 바이너리를 VirusTotal로 검사합니다
- 관리자 검토 — NeboAI 팀이 메타데이터, 매니페스트, 검사 결과를 검토합니다
- 승인 시 — NeboAI가 Ed25519로 앱에 서명하고 게시합니다
- 거부 시 — 사유를 안내받고, 수정해 다시 제출할 수 있습니다
목표 검토 시간: <24시간.
업데이트 배포
- 앱 버전 업데이트: 새 버전으로
PUT /api/v1/developer/apps/{id} - 플랫폼별로 새 바이너리를 업로드합니다
- 다시 검토를 제출합니다
모든 업데이트는 같은 검토 과정을 거칩니다. 새 버전이 승인될 때까지 이전 버전을 계속 사용할 수 있습니다.
스토어 메타데이터
| 필드 | 설명 |
|---|---|
category | 예: productivity, communication, developer-tools |
icon | 앱 아이콘 URL |
visibility | public 또는 private |
description | 매니페스트 설명보다 길고 풍부하게 작성할 수 있습니다 |
개발 워크플로
로컬 개발
로컬 개발에는 패키징이 필요하지 않습니다.
- 앱 디렉터리를 만드세요.
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp manifest.json과 코드를 작성합니다- 바이너리를 빌드하세요.
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo가 새 디렉터리를 자동으로 감지합니다(또는 Nebo를 다시 시작하세요)
- 코드를 바꾼 뒤 바이너리를 다시 빌드하면 파일 감시기가 앱을 다시 시작합니다
로그 보기
앱의 stdout/stderr는 앱별 로그 파일에 기록됩니다.
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 영구 데이터
앱이 보존해야 하는 파일은 data/ 디렉터리(NEBO_APP_DATA 환경 변수로도 제공)를 사용하세요. 이 디렉터리는 앱 업데이트와 격리 후에도 유지됩니다.
디버깅 팁
- 앱이 시작되지 않으면
logs/stderr.log에서 오류를 확인하세요 - 바이너리에 실행 권한이 있는지 확인하세요(
chmod +x binary) NEBO_APP_SOCK의 Unix 소켓 경로에서 수신 대기하고 있는지 확인하세요- 소켓은 실행 후 10초 이내에 준비되어야 합니다
- 저장소에는 하드코딩된 경로 대신
NEBO_APP_DATA를 사용하세요 - 디버그 로그는 stderr로 출력하세요(
logs/stderr.log에 기록됨)
확인
# 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 제거
nebo apps uninstall com.example.myapp 스킬
스킬이란
스킬은 대화 중 Nebo의 행동 방식을 형성하는 지침 모음입니다. 스킬이 활성화되면 그 내용이 시스템 프롬프트에 바로 주입되어, 해당 세션에서 AI 직원의 말투, 방법론, 전문 지식, 도구 사용을 이끕니다.
스킬은 코드가 아닙니다. YAML 메타데이터가 포함된 마크다운 문서입니다. 컴파일도, 바이너리도, gRPC도 없습니다. 스킬은 디렉터리 안의 SKILL.md 파일 하나입니다. 그게 전부입니다.
스킬은 상황에 따라 일시적으로 작동합니다. 관련이 있을 때(트리거 일치 또는 수동 로드) 활성화되고, 몇 턴 동안 유지되다가 더 이상 필요 없으면 만료됩니다. 덕분에 AI 직원의 컨텍스트가 가볍게 유지됩니다. 지금 필요한 지침만 프롬프트에 들어갑니다.
스킬은 앱을 보완합니다. 앱은 실행 가능한 기능(도구, 채널, 게이트웨이)을 제공합니다. 스킬은 그 도구를 효과적으로 쓰는 방법, 즉 조율 지침을 제공합니다. 캘린더 앱은 Nebo에 일정을 읽고 쓰는 능력을 줍니다. "회의 준비" 스킬은 그 캘린더 앱과 이메일, 웹 검색을 함께 사용해 회의를 어떻게 준비할지 Nebo에 알려 줍니다.
스킬과 앱 비교
| 스킬 | 앱 | |
|---|---|---|
| 형식 | 마크다운(SKILL.md) | 컴파일된 바이너리(.napp) |
| 런타임 | 시스템 프롬프트에 주입 | gRPC로 통신하는 샌드박스 프로세스 |
| 제공하는 것 | 행동 지침, 방법론 | 도구, 채널, UI 패널 |
| 수명 | 세션 범위, TTL 기반 만료 | 항상 실행 중 |
| 만들기 | 마크다운 파일 작성 | 작성, 컴파일, 서명, 패키징 |
| 보안 | 권한 불필요 | 기본 거부 샌드박스 |
빠른 시작
Nebo 스킬 폴더에 디렉터리를 만들고 SKILL.md 파일을 넣으세요.
~/Library/Application Support/Nebo/skills/ # macOS
~/.config/nebo/skills/ # Linux
%AppData%\Nebo\skills\ # Windows mkdir -p ~/.config/nebo/skills/my-skill 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. Nebo는 fsnotify로 스킬 디렉터리를 감시합니다. 스킬은 바로 사용할 수 있으며 다시 시작할 필요가 없습니다. 트리거와 일치하는 말을 하면 자동으로 활성화됩니다.
또는 Nebo에게 직접 요청하세요: "블로그 글 작성용 스킬을 만들어 줘"라고 하면 Nebo가 SKILL.md 파일을 대신 작성합니다.
SKILL.md 형식
모든 스킬은 두 부분으로 이루어진 SKILL.md 파일 하나입니다. --- 표시 사이의 YAML 프런트매터와, 시스템 프롬프트에 주입되는 실제 지침인 마크다운 본문입니다.
| 필드 | 필수 | 기본값 | 설명 |
|---|---|---|---|
name | 예 | — | 고유 식별자(슬러그가 됨) |
description | 예 | — | 스킬 카탈로그에 표시되는 한 줄 설명 |
version | 아니요 | "1.0.0" | 업데이트 추적용 Semver |
author | 아니요 | — | 스킬 작성자 |
priority | 아니요 | 0 | 높을수록 먼저 일치(중요한 재정의는 100 이상) |
max_turns | 아니요 | 4 | 자동 만료 전까지의 비활성 턴 수 |
triggers | 아니요 | [] | 이 스킬을 자동으로 활성화하는 문구(대소문자 구분 없는 부분 문자열 일치) |
tools | 아니요 | [] | 이 스킬이 사용할 것으로 예상되는 도구(참고용) |
dependencies | 아니요 | [] | 함께 설치되어야 하는 다른 스킬 |
tags | 아니요 | [] | 분류 및 검색용 |
platform | 아니요 | [] | 지원 플랫폼: macos, linux, windows(비워 두면 모두) |
스킬 활성화 방식
스킬은 2단계 활성화 모델을 따릅니다: 힌트 후 호출.
1단계: 트리거 일치 — 사용자가 메시지를 보낼 때마다 Nebo는 등록된 모든 스킬에서 트리거 일치 여부를 확인합니다. 일치하는 스킬은 시스템 프롬프트에 힌트로 나타납니다. AI 직원은 힌트를 보고 스킬을 호출할지 결정합니다.
2단계: 호출 — AI 직원은 다음과 같이 호출해 스킬을 불러옵니다.
skill(name: "code-review") 이 호출은 전체 SKILL.md 템플릿을 도구 결과로 반환하고, 호출을 기록하며, 이후 턴에서 템플릿을 시스템 프롬프트에 다시 주입합니다.
TTL과 만료:
- 자동 일치 스킬: 비활성 4턴(
max_turns로 설정 가능) - 수동 로드 스킬: 비활성 6턴
- 다시 호출하면 타이머가 초기화됩니다
- 절대 상한: 세션당 활성 스킬 최대 4개
- 토큰 예산: 활성 스킬 내용 합계 최대 16,000자
스킬 관리
AI 직원은 skill 도구로 스킬을 관리할 수 있습니다.
| 작업 | 설명 | 예시 |
|---|---|---|
catalog | 사용 가능한 모든 스킬 나열 | skill(action: "catalog") |
load | 이 세션에서 활성화 | skill(name: "code-review", action: "load") |
unload | 스킬 비활성화 | skill(name: "code-review", action: "unload") |
create | 디스크에 새 스킬 만들기 | skill(action: "create", content: "...") |
update | 기존 스킬 업데이트 | skill(name: "my-skill", action: "update", content: "...") |
delete | 디스크에서 스킬 삭제 | skill(name: "my-skill", action: "delete") |
좋은 스킬 작성하기
좋은 스킬 템플릿에는 다음이 있습니다.
- 명확한 제목 — AI 직원에게 지금 어떤 모드인지 알려 줍니다
- 핵심 원칙 — 타협할 수 없는 행동 규칙
- 방법론 — 흔한 상황에 대한 단계별 접근법
- 예시 — 사용자 메시지에 대한 구체적인 응답 패턴
- 안티패턴 — 하지 말아야 할 것(모델은 부정적인 예시에서 잘 배웁니다)
팁: 각 스킬은 한 가지 일을 잘해야 합니다. "일반 프로그래밍" 스킬을 만들지 말고 code-review, debugging, api-design을 별도 스킬로 만드세요. AI 직원은 여러 스킬을 동시에 활성화할 수 있습니다.
기본 제공 스킬
Nebo에는 흔한 사용 사례를 다루는 기본 제공 스킬이 포함되어 있습니다.
| 스킬 | 우선순위 | 설명 |
|---|---|---|
onboarding | 100 | 신규 사용자 인사 및 프로필 수집 |
best-friend | 50 | 성격 스킬 — 편하고, 의리 있고, 솔직한 대화 |
debugging | 25 | 체계적인 디버깅 방법론 |
api-design | 15 | RESTful API 설계 모범 사례 |
code-review | 10 | 심각도 수준별 구조화된 코드 리뷰 |
database-expert | 10 | 데이터베이스 설계, 쿼리, 최적화 |
git-workflow | 10 | Git 브랜치, 커밋, PR 워크플로 |
security-audit | 10 | 보안 분석 및 취약점 탐지 |
이 스킬들은 유용한 기본값이자, 나만의 스킬을 만들 때 참고할 수 있는 구현 예시입니다.
참조
Proto 파일
Proto 파일은 proto/apps/v0/에 있습니다. SDK에 미리 생성된 코드가 포함되어 있으므로 일반적인 개발에는 protoc가 필요하지 않습니다.
| 파일 | 서비스 | 주요 RPC |
|---|---|---|
v0/common.proto | (메시지 전용) | HealthCheckRequest/Response, SettingsMap, UserContext, Empty |
v0/tool.proto | ToolService | Name, Description, Schema, Execute, RequiresApproval, Configure |
v0/channel.proto | ChannelService | ID, Connect, Disconnect, Send, Receive(스트림), Configure |
v0/comm.proto | CommService | Name, Version, Connect, Disconnect, Send, Subscribe, Register, Receive(스트림), Configure |
v0/gateway.proto | GatewayService | HealthCheck, 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(스트림), Configure |
모든 서비스에는 HealthCheck와 Configure RPC가 포함됩니다. 둘 다 SDK가 자동으로 처리합니다.
채널 Proto 유형
| 메시지 유형 | 설명 |
|---|---|
ChannelSendRequest | message_id, channelId, sender, text, attachments, reply_to, actions, platform_data가 포함된 발신 메시지 봉투 |
ChannelSendResponse | 스레드용 플랫폼 메시지 ID |
InboundMessage | 모든 공통 필드와 timestamp가 포함된 수신 메시지 봉투 |
MessageSender | 봇 정체성(name, role, botId) — 브로커가 보강 |
Attachment | 파일/이미지/오디오 첨부(type, url, filename, size) |
MessageAction | 대화형 버튼/키보드 동작(label, callback_id) |
봇 정체성과 역할
Nebo 봇은 세 축으로 이루어진 정체성 모델을 가집니다.
- creature — 봇이 무엇인지(원형): "재치 있는 전략가", "꼼꼼한 연구자"
- role — 사용자와의 관계: "친구", "COO", "멘토"
- vibe — 봇의 에너지(소통 스타일): "느긋하지만 소신 있음", "따뜻하고 격려하는"
채널 플러그인이 발신 메시지를 받으면 sender 필드에 봇의 name과 role이 들어 있습니다. 이를 사용해 플랫폼에 맞게 표시 이름을 구성하세요. 역할은 직함이 아니라 관계를 나타냅니다. "COO", "DevLead"와 함께 "친구", "아들", "멘토"도 유효한 역할입니다.