@zibby/skills 0.2.2 → 0.2.4

package/docs/self-host/custom-sidecars.md

@@ -0,0 +1,136 @@
+---
+sidebar_position: 5
+title: Custom (BYO) sidecars
+---
+
+# Bring your own sidecar
+
+A **sidecar** is a long-lived service container the box runs next to your
+agents — the platform's own vector-KB engine and OAuth token broker ship this
+way. On a self-hosted box you can also register **your own** sidecar image.
+That is the standard way to add a custom resident service to the platform —
+most commonly a **thin MCP server that wraps an internal REST API**, so your
+agents and the chat Copilot can call systems that only exist inside your
+network.
+
+No marketplace entry, no platform code change, no third-party registry: you
+push a `docker save` tarball to your own box, the box pins its sha256, and the
+sidecar flows through the exact same launch/health/idle-reap machinery as the
+built-ins.
+
+:::tip Wrapping a REST API? Try the OpenAPI bridge agent first.
+
+If all you need is "my agents should be able to call this internal REST API",
+you probably do **not** need to build an image at all. Deploy the **OpenAPI MCP
+Bridge** agent from the marketplace, put your API's spec URL in its **Env** tab,
+and every operation in the spec becomes an MCP tool — no code, no upload.
+
+```json
+OPENAPI_APIS = {"billing":{"specUrl":"https://internal/v2/api-docs","root":"https://internal"}}
+```
+
+It is a marketplace agent that carries its own sidecar, so deploying it is the
+whole installation. Build your own image (below) when you need logic the bridge
+can't express — a non-HTTP protocol, a stateful session, custom auth.
+:::
+
+## Push one
+
+```bash
+# 1. Build your image however you like; it must serve HTTP on one port.
+docker build -t report-mcp:0.1.0 .
+docker save report-mcp:0.1.0 | gzip > report-mcp.tar.gz
+
+# 2. Push it to the box. Needs an OPERATOR access token
+#    (a restricted per-user token is refused).
+zibby sidecar push report-mcp.tar.gz \
+  --name report-mcp --port 8080 \
+  --health-path /health \
+  --warm \
+  --api-url https://your-box.example.com --token $OPERATOR_PAT
+```
+
+`push` streams the tarball up (`POST /selfhost/sidecars/artifacts`), then
+registers the declaration (`PUT /selfhost/sidecars/report-mcp`) pinned to the
+sha256 the server computed from the uploaded bytes. The image is verified and
+`docker load`ed **before** anything is persisted — a corrupt or tampered
+tarball can never become a registered sidecar.
+
+Manage what's registered:
+
+```bash
+zibby sidecar list             # custom sidecars + the reserved built-in names
+zibby sidecar remove <name>    # unregister + stop (image reclaimed; data volume kept) (data volumes are kept)
+```
+
+## Reach it
+
+- **From the control plane / the chat Copilot** — the container listens on the
+  box's infra network at `http://zibby-sidecar-<name>:<port>`. Agent run
+  containers deliberately **cannot** dial it directly (they are isolated on the
+  run network); access is brokered by the platform.
+- **From a browser / third-party client** — every `--public-path` prefix is
+  served at `https://<box-origin>/sidecars/<name>/<path>` through the
+  control-plane reverse proxy. Anything not declared public stays
+  infra-network-only.
+
+:::warning `--public-path` is opt-in, and most sidecars don't need it
+A declared public path is reachable **anonymously** — the platform adds no auth
+and no identity; your app owns that surface entirely. Agents and the chat
+Copilot reach a sidecar over the infra network, so an MCP server for them needs
+**no** public path. It exists for browser flows (an OAuth callback a provider
+redirects to). Registering one is therefore refused unless the box opts in with
+`SIDECAR_BYO_PUBLIC_PATHS=1` in its `.env` (then restart the control-plane).
+:::
+
+### Wire it into the Copilot
+
+For the "internal API → MCP → chat" use case, register the sidecar and then
+attach its MCP endpoint to the Copilot (in chat):
+
+> connect yourself to the MCP at `http://zibby-sidecar-report-mcp:8080/mcp`
+
+The Copilot can also drive the whole flow itself with the owner-only tools
+`zibby_add_sidecar` (takes a downloadable `url` + pinned `sha256` instead of a
+file upload), `zibby_list_sidecars`, and `zibby_remove_sidecar`.
+
+## Declaration reference
+
+| Flag | Meaning |
+|---|---|
+| `--name` | `[a-z][a-z0-9-]{1,30}`. Built-in names (`gbrain`, `pingcode`, …) are reserved. |
+| `--port` | The HTTP port your app listens on inside the container. Required. |
+| `--version` | Display/tag version (default: first 12 chars of the sha256). |
+| `--health-path` | GET path returning 2xx when ready (default `/health`). |
+| `--public-path` | Repeatable. Path prefix exposed through the public reverse proxy — **anonymously**. Disabled unless the box sets `SIDECAR_BYO_PUBLIC_PATHS=1`; see below. |
+| `--warm` | Keep it always-on (pre-warmed at boot, never idle-reaped). Default: on-demand launch + idle reap. |
+| `--env-key` | Repeatable. A box `.env` variable forwarded into the container when set. |
+| `--request-config-key` | Repeatable. Per-agent config: resolved from the **calling agent's encrypted Env bag** and sent per request — one shared container can serve N projects with different upstream credentials. |
+| `--data-path` | Container path persisted on a named volume (survives restarts; kept on remove). |
+| `--memory-bytes` | Container memory cap. |
+
+## What the box guarantees
+
+- **sha256-pinned, always.** The tarball's hash is computed server-side at
+  upload and re-verified on every subsequent load — including the re-fetch
+  path: the verified tarball is kept in the box's own object store, so if the
+  docker image is ever pruned it is restored automatically without a re-upload.
+- **Operator-only surface.** Upload/register/remove require the box
+  owner/admin token; restricted per-user tokens get `403`.
+- **Isolation unchanged.** Custom sidecars get the same placement as built-in
+  ones: infra network, brokered access, no host mounts — the declaration
+  cannot ask for privileged options.
+- **No shadowing, at BOTH layers.** A custom sidecar can never take over a
+  built-in sidecar's *name*, and its package can never take over a platform or
+  another sidecar's *image tag*: the archive's manifest is read **before**
+  `docker load` runs, and a package declaring `zibby-*` or another sidecar's
+  image is refused outright — even if that image isn't on the box yet.
+- **Uninstall reclaims storage.** Removing a sidecar deletes its image; a
+  superseded image is reclaimed when you push a new version. The declared data
+  volume is **kept** (it holds your content) — the response tells you its name,
+  and `zibby sidecar remove <name> --purge-data` deletes it deliberately.
+
+:::note Cloud
+BYO sidecars are **self-host only** today. On cloud, wrap an external API as a
+remote MCP server and attach it with `zibby_add_mcp` instead.
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Built-in skill definitions for the Zibby agent-workflow framework",
   "type": "module",
   "main": "dist/index.js",
@@ -115,7 +115,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@resvg/resvg-js": "^2.6.2",
-    "@zibby/agent-workflow": "^0.4.0",
+    "@zibby/agent-workflow": "^0.6.1",
     "@zibby/bin-oxlint": "^1.73.0",
     "@zibby/bin-semgrep": "^1.169.0",
     "@zibby/skill-ids": "^0.2.0",