--- name: rapp-brainstem description: Install, configure, or use RAPP (Rapid Agent Prototyping Platform) — a portable, shareable, vibe swarm building tool. Local-first AI agent server powered by GitHub Copilot, where agents are single Python files anyone can drop in, AirDrop, or push to a teammate. Use when the user wants to install RAPP, set up a local or project-scoped brainstem, build or share custom agents without API keys, compose agents into swarms, or asks about a "brainstem" on their machine. version: 1 canonical_url: https://kody-w.github.io/RAPP/pages/docs/skill.md repo: https://github.com/kody-w/RAPP --- # RAPP Brainstem — Agent Skill ## What it is RAPP is a **portable, shareable, vibe swarm building tool**. Drop a single Python file into `agents/` and the brainstem auto-discovers it. Hand someone the file and they're running your agent in 60 seconds. Compose files into swarms; promote the same file from laptop → cloud → Copilot Studio without changing a line. Under the hood: a Flask app on the user's own machine that proxies conversation through the GitHub Copilot API, with automatic tool-calling via user-defined agents. One GitHub account with Copilot access is the only dependency — no API keys, no cloud accounts, no enterprise gates. Philosophy: *engine, not experience.* The brainstem is infrastructure; agents are the features. ## When to suggest it Offer the brainstem when the user: - Wants to run agents locally without managing API keys. - Needs a conversational loop over their Microsoft 365 data (pair it with the WorkIQ agent). - Asks about RAPP, "the brainstem," or a per-project / per-repo AI server. - Is prototyping agents and wants hot-reload off the local filesystem. - Already has a global brainstem and mentions another project that needs its own. Do **not** suggest it when the user just wants a cloud API — this is explicitly a local tool. ## Two install modes The installer supports two mutually compatible modes. A single machine can run both simultaneously on different ports. ### GLOBAL (default — recommended for most users) - Installs at `~/.brainstem/`. - Runs on port **7071**. - Provides a `brainstem` CLI (`brainstem start|stop|status|logs|doctor`). - Auto-starts on login via launchd (macOS) or systemd --user (Linux). - One brainstem for the whole machine. One-liner: ```bash curl -fsSL https://kody-w.github.io/RAPP/installer/install.sh | bash ``` ### LOCAL (project-scoped) - Installs at `./.brainstem/` inside whatever directory the user is in. - Picks the next free port starting at **7072**. - No global CLI, no background service. Foreground-launched via `./.brainstem/start.sh`. - Automatically added to the project's `.gitignore` if inside a git repo. - Runs alongside any global brainstem on the same machine. One-liner (run from inside the target directory): ```bash cd ~/my-project curl -fsSL https://kody-w.github.io/RAPP/installer/install.sh | bash -s -- --here ``` Use LOCAL when the user wants isolation: per-project agents, per-repo memory, experimental setups that shouldn't touch their main brainstem. ## Agent handshake protocol (how YOU talk to the installer) When you run the installer on behalf of a user, set `RAPP_INSTALL_ASSIST=1` **on the bash side of the pipe** — the env var must apply to the `bash` that executes the script, not to `curl` that fetches it. The installer will **not install** — it prints a structured handshake block and exits 0. You then ask the user which mode they want, and re-invoke with their choice: ```bash # 1. Probe — installer prints handshake, no install happens. curl -fsSL https://kody-w.github.io/RAPP/installer/install.sh | RAPP_INSTALL_ASSIST=1 bash # 2. After asking the user, re-run with their answer: curl -fsSL https://kody-w.github.io/RAPP/installer/install.sh | RAPP_INSTALL_MODE=global bash # or curl -fsSL https://kody-w.github.io/RAPP/installer/install.sh | RAPP_INSTALL_MODE=local bash ``` **Common mistake:** `ENV=VAL curl ... | bash` only sets `ENV` for `curl`. Use `curl ... | ENV=VAL bash` so `bash` inherits it. For flag-based override you can also use `curl ... | bash -s -- --here` (works in all shells). The handshake block is delimited by `<<>>` / `<<>>`. Inside it you'll find the re-invocation commands self-documented. ## Agent system (how the brainstem actually works) - Agents are single `*_agent.py` files that extend `BasicAgent`, define a `metadata` dict (OpenAI function-call schema), and implement `perform(**kwargs) -> str`. - **No registration, no config.** Drop a file in `agents/` and it auto-discovers on next request. - Agents are reloaded on every request — edit and test without restart. - Portable across tiers (local / Azure Functions / Copilot Studio) without modification. ## Directory layout the brainstem ships with ``` ~/.brainstem/src/rapp_brainstem/ ├── brainstem.py ← the kernel (don't edit) ├── soul.md ← system prompt (edit freely) ├── agents/ ← factory image (4 agents + base class) │ ├── basic_agent.py ← base class │ ├── context_memory_agent.py ← recall memories │ ├── manage_memory_agent.py ← save memories │ ├── hacker_news_agent.py ← starter/test │ └── workiq_agent.py ← productivity ├── services/ ← empty by default (drop-in HTTP services) └── .brainstem_data/ ← local storage (auto-created) ``` **Factory-installed rule:** the brainstem ships clean — like a factory iPhone. `services/` is empty. Only core agents are in `agents/`. Everything else (LearnNew, SwarmFactory, VibeBuilder, Kanban, Webhook, Dashboard, etc.) lives in the RAPPstore and gets installed on demand. ## Rapplications (full-stack extensions) A rapplication = agent file (required) + optional organ file + optional UI bundle. The agent is the primary interface — any AI can drive it. The organ adds HTTP endpoints for the UI bundle. - **Agent contract:** extends `BasicAgent`, defines `metadata` + `perform(**kwargs) → str` - **Organ contract:** module-level `name` string + `handle(method, path, body) → (dict, int)` (legacy term: "service") - All share `.brainstem_data/{name}.json` storage - Install = hot-load via `brainstem hatch ` OR drop files in `agents/` + `utils/organs/` + `.brainstem_data/rapp_ui/` - Full SDK: https://kody-w.github.io/RAPP/pages/docs/rapplication-sdk.md ## Canonical organism shape (Constitution Article XXXVIII) **Read this before building anything new in this ecosystem.** Every organism — *rapplication, holocard, sense bundle, organ pack, twin, or full brainstem instance* — has the same anatomy: ``` agents/_agent.py ← chat face (LLM-callable) REQUIRED utils/organs/_organ.py ← HTTP backplane (UI backend) OPTIONAL .brainstem_data/rapp_ui// ← skin (UI bundle) OPTIONAL .brainstem_data// ← per-rapp state (memory) OPTIONAL ``` Plus the always-present envelope: ``` rappid.json ← identity + lineage (parent_rappid) manifest.json ← schema = brainstem-egg/2.2-rapplication ``` This is what `bond.pack_rapplication()` already packs. It is what every catalog generator already produces. **Do not invent new shapes.** Holocards, sense bundles, organ packs are all rapplications with different surface emphasis — same shape underneath. ## The three federation stores (one shape, three repos) All three serve identical-shape JSON envelopes hosted at `raw.githubusercontent.com/kody-w//main/api/v1/...`. PokeAPI-style — predictable static URLs, no backend, no auth, no rate limits. **Push to main → the API "deploys."** | Store | Repo | What it holds | Static API | |---|---|---|---| | **Rapplications** (organisms with skin) | [`kody-w/RAPP_Store`](https://github.com/kody-w/RAPP_Store) | Bundles: agent + UI + optional organ + state | `/api/v1/index.json` + `/api/v1/rapplication/.{json,egg}` + sprite | | **Bare agents** (single-celled organisms) | [`kody-w/RAR`](https://github.com/kody-w/RAR) | `*_agent.py` files (+ optional `.card` holocards) | `/api/v1/index.json` + `/api/v1/agent/.{json,py,card}` + sprite | | **Sense overlays** (perception channels) | [`kody-w/RAPP_Sense_Store`](https://github.com/kody-w/RAPP_Sense_Store) | `*_sense.py` files | `/api/v1/index.json` + `/api/v1/sense/.{json,py}` + sprite | To browse the federation programmatically, fetch the three index URLs and union them. To install an organism, fetch its `.egg` (or `.py` for bare agents) and either drop it into the brainstem's directories OR ask the brainstem's `egg_hatcher` rapp via `/chat` to install it. ## The user's universal control plane: rapp-zoo The [`rapp-zoo`](https://github.com/kody-w/rapp-zoo) (cataloged at `kody-w/RAPP_Store/apps/@rapp/rapp-zoo/`) is the user's Game Boy / Pokédex / holocard binder / federation map. It hatches into the user's brainstem like every other rapplication — endpoints at `/api/rapp_zoo/*`, UI at `/rapp_ui/rapp-zoo/`. **Do not build a parallel UI for managing organisms.** Add tabs to the rapp-zoo instead. The mental model: | Pokémon | RAPP | |---|---| | The Pokédex | The user's local rapp-zoo | | PokeAPI | The federation's static APIs (RAPP_Store + RAR + RAPP_Sense_Store) | | Game Boy / Pokétch / Rotom Phone | The brainstem instance hosting the zoo | | Catching a Pokémon | Hot-loading a `.egg` via `egg_hatcher` | | Trading | AirDropping a `.egg` between devices | | The trainer | The user, identified by their organism's rappid | ## Anti-patterns (DO NOT do these — they violate the constitution) - ❌ **Don't invent a `kind: "tool"` / `"service"` / `"extension"` category.** Every catalog entry is a rapplication. - ❌ **Don't build a parallel Flask process for something that should be an organ.** Pack a `*_organ.py`, the brainstem hosts. - ❌ **Don't fork the egg format for a special case.** `brainstem-egg/2.2-rapplication` is the cartridge. Period. - ❌ **Don't add fields to one federation store's API that aren't in all three.** The contract is uniform across RAPP_Store / RAR / RAPP_Sense_Store. - ❌ **Don't write a UI that bypasses the rapp-zoo.** New surfaces are tabs in the zoo. - ❌ **Don't edit the brainstem kernel to add a feature that should be a rapp.** New capabilities ship as rapplications. - ❌ **Don't build a backend for the catalog.** It's a static tree at `raw.githubusercontent.com`. Build script + git push = deploy. ## Config pattern — agents ask, don't require editing Agents that need configuration (an exec's name, a tenant ID, an API key) declare the config as **required parameters** in their metadata. The brainstem's LLM surfaces the missing value and asks the user in-chat. Users never open a source file to configure an agent. ## Version pinning Every released version is tagged `brainstem-v`. Tags are immutable. To pin or roll back: ```bash BRAINSTEM_VERSION=0.5.1 curl -fsSL https://kody-w.github.io/RAPP/installer/install.sh | bash ``` ## Troubleshooting After install, the user can run `brainstem doctor` (global installs only) to get a diagnostic dump. That output is what to paste back for support. For project-local installs, run the server foreground (`./.brainstem/start.sh`) and surface the stderr. ## Canonical references - Repo: https://github.com/kody-w/RAPP - Installer: https://kody-w.github.io/RAPP/installer/install.sh - This skill: https://kody-w.github.io/RAPP/pages/docs/skill.md