Kontraknya
Sidecar adalah server gRPC pada socket Unix. Dengarkan path di NEBO_APP_SOCK dan implementasikan apps.v0.UIService. Nebo memanggil HandleRequest untuk setiap permintaan; HealthCheck dan Configure adalah bagian dari layanan tetapi saat ini tidak dipanggil. Socket harus muncul dalam startup_timeout manifes, yang default-nya 10 detik dan paling lama 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;
} Sidecar berjalan di macOS dan Linux.
Tempat Nebo menemukan biner
Di folder aplikasi, Nebo menggunakan yang pertama ada dari daftar berikut:
- File bernama
binary - File bernama
app - File pertama di
tmp/ - File pertama di
bin/ - Executable pertama di
sidecar/target/release/, untuk pengembangan lokal
Biner harus berupa file biasa yang dapat dieksekusi, bukan symbolic link, dan paling besar 500 MB. Aplikasi yang dipublikasikan menyimpannya di bin/<name>. Saat file berubah di disk, Nebo memulai ulang sidecar.
Lingkungan
Sidecar dimulai dengan lingkungan kosong dan variabel-variabel berikut:
| Variabel | Nilai |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | Identitas aplikasi. |
NEBO_APP_DIR | Folder aplikasi. |
NEBO_APP_SOCK | Socket yang didengarkan, <app folder>/<id>.sock. Nebo mengatur mode-nya ke 0600. |
NEBO_DATA_DIR | Folder data aplikasi, <data>/appdata/agents/<id>/. Juga merupakan direktori kerja. |
NEBO_API_URL | API lokal bot, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Token untuk memanggil API aplikasi bot. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Diteruskan. |
Output standar dan error standar masuk ke sidecar.log di folder data. Input standar berupa pipe; akhir file berarti Nebo sudah berhenti dan sidecar harus keluar. Sidecar berjalan dalam grup prosesnya sendiri.
Permintaan dari halaman
Permintaan ke /apps/<id>/api/<path>, yang dibuat halaman dengan neboFetch dan path relatif, sampai ke HandleRequest dengan path diatur ke <path>. Path yang diawali _ ditolak. Isi permintaan dibatasi 10 MB dan respons 32 MB.
Alat untuk karyawan
Deklarasikan alat di agent.json aplikasi. Masing-masing menjadi alat bernama app__<app>__<name>, yang dimuat saat karyawan membutuhkannya. Sebuah panggilan menjadi permintaan ke sidecar pada method dan 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" } } }
}
] Memanggil Nebo
Sidecar dapat menggunakan layanan yang sama dengan halaman dengan memanggil $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... menggunakan header Authorization: Bearer $NEBO_APP_TOKEN.
| Rute | Fungsi |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | Penyimpanan key-value aplikasi. |
POST /agents/invoke, POST /agents/stream | Bertanya kepada karyawan: {message, agent, data}. Respons stream berupa server-sent events. |
POST /janus/complete, POST /janus/stream | Panggilan model langsung: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Permintaan keluar, {url, method, headers, body}, yang diizinkan oleh izin network: aplikasi. |
GET /identity | Karyawan aplikasi. |
Siklus hidup
- Nebo memeriksa socket setiap tiga detik.
- Sidecar yang gagal dimulai ulang setelah satu detik, berlipat ganda hingga paling lama 60 detik. Setelah lima kegagalan berturut-turut, sidecar ditandai gagal. Sidecar yang bertahan aktif selama 60 detik dianggap sehat kembali.
- Permintaan ke sidecar yang berhenti akan memulainya dan menunggu hingga 15 detik. Permintaan GET dan HEAD dicoba ulang.
- Untuk menghentikan sidecar, Nebo mengirim SIGTERM ke grup prosesnya, lalu mematikannya setelah dua detik.