App Sidecar

Frontend                  Nebo Server                    Sidecar
--------                  -----------                    -------
nebo.fetch('/projects')
  |
  +- SDK builds URL:
  |  {base}/api/v1/apps/{id}/api/projects
  |
  +---- HTTP GET -------->  proxy_to_sidecar()
                              |
                              +- Extracts method, path,
                              |  query, headers, body
                              |
                              +- Connects to Unix socket
                              |  {app_dir}/{id}.sock
                              |
                              +---- gRPC HandleRequest -->  UIService
                                    HttpRequest {              |
                                      method: "GET"            +- Routes path
                                      path: "projects"         |  to handler
                                      query: ""                |
                                      headers: {...}           +- Processes
                                      body: []                 |  request
                                    }                          |
                                                               +- Returns
                              <---- HttpResponse ----------------+
                              HttpResponse {
                                status_code: 200
                                headers: {"content-type": "application/json"}
                                body: [{"id":"abc","name":"My Project",...}]
                              }
                              |
  <---- HTTP 200 -------------+
  JSON body returned to caller

// GET -- list resources
const resp = await nebo.fetch('/projects');
const projects = await resp.json();

// POST -- create a resource
const resp = await nebo.fetch('/projects', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'New Project' })
});

// PUT -- update a resource
await nebo.fetch('/projects/abc', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Updated Name' })
});

// DELETE -- remove a resource
await nebo.fetch('/projects/abc', { method: 'DELETE' });

// Query strings work naturally
const resp = await nebo.fetch('/documents?project_id=abc&format=pdf');

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, etc.
  string path = 2;                 // Path relative to /apps/{id}/api/
  string query = 3;                // Raw query string (e.g. "page=1&size=10")
  map<string, string> headers = 4; // Request headers
  bytes body = 5;                  // Request body (empty for GET/HEAD)
}

message HttpResponse {
  int32 status_code = 1;           // HTTP status code (200, 404, 500, etc.)
  map<string, string> headers = 2; // Response headers
  bytes body = 3;                  // Response body
}

use proto::{HttpRequest, HttpResponse};

async fn handle_http(&self, method: &str, path: &str, query: &str, body: &[u8]) -> HttpResponse {
    let parts: Vec<&str> = path.trim_start_matches('/')
        .split('/')
        .filter(|s| !s.is_empty())
        .collect();

    match (method, parts.as_slice()) {
        // GET /projects -- list all projects
        ("GET", &["projects"]) => {
            let projects = self.state.list_projects().await;
            json_response(200, &projects)
        }
        // POST /projects -- create a project
        ("POST", &["projects"]) => {
            let req: CreateRequest = serde_json::from_slice(body)?;
            let project = self.state.create_project(req).await;
            json_response(201, &project)
        }
        // GET /projects/{id} -- get one project
        ("GET", &["projects", id]) => {
            match self.state.get_project(id).await {
                Some(p) => json_response(200, &p),
                None => json_response(404, &json!({  "error": "not found" })),
            }
        }
        _ => json_response(404, &json!({ "error": "not found" }))
    }
}

fn json_response<T: serde::Serialize>(status: i32, data: &T) -> HttpResponse {
    HttpResponse {
        status_code: status,
        headers: HashMap::from([("content-type".into(), "application/json".into())]),
        body: serde_json::to_vec(data).unwrap_or_default(),
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sock_path = std::env::var("NEBO_APP_SOCK")
        .unwrap_or_else(|_| "/tmp/my-app.sock".into());
    let data_dir = std::env::var("NEBO_APP_DATA")
        .unwrap_or_else(|_| "data".into());

    // Clean stale socket
    let _ = std::fs::remove_file(&sock_path);

    let service = MyAppService::new(&data_dir);

    let uds = tokio::net::UnixListener::bind(&sock_path)?;
    let uds_stream = tokio_stream::wrappers::UnixListenerStream::new(uds);

    tonic::transport::Server::builder()
        .add_service(UiServiceServer::new(service))
        .serve_with_incoming(uds_stream)
        .await?;

    Ok(())
}

// In your handle_http match block:
("GET", &["_tools"]) => {
    let tools = serde_json::json!([
        {
            "name": "list_projects",
            "description": "List all projects for the current user",
            "method": "GET",
            "path": "/projects"
        },
        {
            "name": "create_project",
            "description": "Create a new project with a name and optional description",
            "method": "POST",
            "path": "/projects",
            "input_schema": {
                "type": "object",
                "properties": {
                    "name": { "type": "string", "description": "Project name" },
                    "description": { "type": "string", "description": "Optional description" }
                },
                "required": ["name"]
            }
        },
        {
            "name": "get_project",
            "description": "Get a single project by ID",
            "method": "GET",
            "path": "/projects/{id}"
        }
    ]);
    json_response(200, &tools)
}

{
  "skills": ["skills/workspace-management", "skills/document-editing"],
  "requires": { "plugins": ["gws"] },
  "scopes": {
    "editor": {
      "tools": ["get_document", "update_document", "get_comments", "add_comment"],
      "skills": ["skills/document-editing"]
    },
    "projects": {
      "tools": ["list_projects", "create_project", "search_documents"],
      "skills": ["skills/workspace-management"],
      "plugins": ["gws"]
    }
  }
}

// Document editing view -- only document tools + skills
nebo.chat.mount(container, {
  contextId: doc.id,
  scope: 'editor'
});

// Project overview -- different tools + skills + plugins
nebo.chat.mount(container, {
  contextId: 'projects',
  scope: 'projects'
});

// No scope -- all tools/skills/plugins available (default)
nebo.chat.mount(container, {
  contextId: 'general'
});

mkdir -p "$NEBO_DATA/user/agents/my-app/ui"

# Work from a source repo, symlink into Nebo
ln -s /path/to/my-app "$NEBO_DATA/user/agents/my-app"

1. developer(resource: account, action: select, id: "your-dev-account-id")
2. agent(action: create, name: "deal-tracker", manifestContent: "# Deal Tracker\n...")
3. agent(action: binary-token, id: "AGENT_ID")
4. Upload binary via returned curl command (per platform)
5. agent(action: submit, id: "AGENT_ID", version: "1.0.0")