| 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:
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):
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:
curl -fsSL https://kody-w.github.io/RAPP/installer/install.sh | RAPP_INSTALL_ASSIST=1 bash
curl -fsSL https://kody-w.github.io/RAPP/installer/install.sh | RAPP_INSTALL_MODE=global bash
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 <<<RAPP_INSTALLER_HANDSHAKE v=1>>> / <<<END_RAPP_INSTALLER_HANDSHAKE>>>. 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 <egg-url> 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/<name>_agent.py ← chat face (LLM-callable) REQUIRED
utils/organs/<name>_organ.py ← HTTP backplane (UI backend) OPTIONAL
.brainstem_data/rapp_ui/<id>/ ← skin (UI bundle) OPTIONAL
.brainstem_data/<id>/ ← 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/<store>/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 | Bundles: agent + UI + optional organ + state | /api/v1/index.json + /api/v1/rapplication/<id>.{json,egg} + sprite |
| Bare agents (single-celled organisms) | kody-w/RAR | *_agent.py files (+ optional .card holocards) | /api/v1/index.json + /api/v1/agent/<id>.{json,py,card} + sprite |
| Sense overlays (perception channels) | kody-w/RAPP_Sense_Store | *_sense.py files | /api/v1/index.json + /api/v1/sense/<id>.{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.
2026-05-10: the .egg extension now carries five cartridge kinds (organism / rapplication / session / neighborhood / estate). The kernel agent egg_hatcher_agent.py introspects any .egg from a path or URL, reads manifest.schema/type, and routes by kind — refusing on unknown kinds. Session cartridges are workflow snapshots that mount in a console iframe (pages/vbrainstem.html or rappterbox); neighborhood and estate cartridges are planned. See SPEC.md §18.10–§18.11.
The user's universal control plane: rapp-zoo
The 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<X.Y.Z>. Tags are immutable. To pin or roll back:
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
