NeboAI
NeboAI
시작하기

앱 사이드카

사이드카는 앱 옆에서 실행되는 바이너리입니다. 페이지의 API를 제공하고, 앱의 데이터를 보관하고, 앱 직원에게 도구를 줍니다. Nebo가 사이드카를 시작하고, 로컬 소켓으로 요청을 전달하며, 실패하면 다시 시작합니다.

계약

사이드카는 Unix 소켓 위의 gRPC 서버입니다. NEBO_APP_SOCK의 경로에서 수신 대기하고 apps.v0.UIService를 구현하세요. Nebo는 모든 요청에 대해 HandleRequest를 호출합니다. HealthCheck와 Configure는 서비스의 일부이지만 현재는 호출되지 않습니다. 소켓은 매니페스트의 startup_timeout 안에 나타나야 하며, 기본값은 10초이고 최대 120초까지 설정할 수 있습니다.

syntax = "proto3";
package apps.v0;

service UIService {
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Configure(SettingsMap) returns (Empty);
  rpc HandleRequest(HttpRequest) returns (HttpResponse);
}

message HttpRequest {
  string method = 1;               // GET, POST, PUT, DELETE, ...
  string path = 2;                 // relative to /apps/{id}/api/
  string query = 3;                // raw query string
  map<string, string> headers = 4;
  bytes body = 5;
}

message HttpResponse {
  int32 status_code = 1;
  map<string, string> headers = 2;
  bytes body = 3;
}

사이드카는 macOS와 Linux에서 실행됩니다.

Nebo가 바이너리를 찾는 위치

Nebo는 앱 폴더에서 다음 중 처음으로 존재하는 것을 사용합니다.

  1. binary라는 이름의 파일
  2. app이라는 이름의 파일
  3. tmp/의 첫 번째 파일
  4. bin/의 첫 번째 파일
  5. 로컬 개발용으로, sidecar/target/release/의 첫 번째 실행 파일

바이너리는 심볼릭 링크가 아닌 일반 실행 파일이어야 하며, 최대 500 MB입니다. 게시된 앱은 바이너리를 bin/<name>에 둡니다. 디스크의 파일이 바뀌면 Nebo가 사이드카를 다시 시작합니다.

환경

사이드카는 빈 환경에서 다음 변수만 가지고 시작합니다.

변수값
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION앱의 식별 정보.
NEBO_APP_DIR앱의 폴더.
NEBO_APP_SOCK수신 대기할 소켓, <app folder>/<id>.sock. Nebo가 모드를 0600으로 설정합니다.
NEBO_DATA_DIR앱의 데이터 폴더, <data>/appdata/agents/<id>/. 작업 디렉터리이기도 합니다.
NEBO_API_URL봇의 로컬 API, http://127.0.0.1:<port>.
NEBO_APP_TOKEN봇의 앱 API를 호출하기 위한 토큰.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ그대로 전달됩니다.

표준 출력과 표준 오류는 데이터 폴더의 sidecar.log로 갑니다. 표준 입력은 파이프이며, 파일 끝(EOF)은 Nebo가 사라졌다는 뜻이므로 사이드카가 종료해야 합니다. 사이드카는 자체 프로세스 그룹에서 실행됩니다.

페이지에서 오는 요청

페이지가 neboFetch와 상대 경로로 보내는 /apps/<id>/api/<path> 요청은 path가 <path>로 설정된 채 HandleRequest에 도달합니다. _로 시작하는 경로는 거부됩니다. 요청 본문은 10 MB, 응답은 32 MB로 제한됩니다.

직원을 위한 도구

앱의 agent.json에 도구를 선언하세요. 각 도구는 app__<app>__<name>이라는 이름의 도구가 되며, 직원이 필요할 때 로드됩니다. 호출은 사이드카의 method와 path로 가는 요청이 됩니다.

"tools": [
  {
    "name": "list_deals",
    "description": "List open deals, optionally filtered by stage.",
    "method": "GET",
    "path": "/deals",
    "input_schema": { "type": "object", "properties": { "stage": { "type": "string" } } }
  }
]

Nebo 호출하기

사이드카는 Authorization: Bearer $NEBO_APP_TOKEN 헤더와 함께 $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/...를 호출해 페이지와 같은 서비스를 사용할 수 있습니다.

경로하는 일
GET /storage, GET|PUT|DELETE /storage/<key>앱의 키-값 저장소.
POST /agents/invoke, POST /agents/stream직원에게 묻기: {message, agent, data}. 스트림 응답은 server-sent events입니다.
POST /janus/complete, POST /janus/stream직접 모델 호출: {messages, model, temperature, max_tokens, system}.
POST /http/proxy앱의 network: 권한이 허용하는 외부 요청, {url, method, headers, body}.
GET /identity앱의 직원.

수명 주기

  • Nebo는 3초마다 소켓을 점검합니다.
  • 실패한 사이드카는 1초 후 다시 시작하며, 대기 시간은 두 배씩 늘어나 최대 60초가 됩니다. 연속 다섯 번 실패하면 실패로 표시됩니다. 60초 동안 계속 실행된 사이드카는 다시 정상 상태가 됩니다.
  • 중지된 사이드카로 요청이 오면 사이드카를 시작하고 최대 15초 동안 기다립니다. GET과 HEAD 요청은 재시도됩니다.
  • 사이드카를 중지할 때 Nebo는 프로세스 그룹에 SIGTERM을 보내고, 2초 후 강제 종료합니다.