run - SKILL.md Agent Skill

name: run description: Run an existing Reboot application locally. Detects whether the project is an MCP Chat App or a standalone Web App, makes sure dependencies and secrets are in place, then starts every process the app needs — the backend (`rbt dev run`) and the frontend dev server (for Chat Apps it also opens the setup wizard, from which the user can launch MCPJam on demand). Use this to bring an app back up, e.g. at the start of a new session. argument-hint: [] allowed-tools: Bash, Read, Write, Glob, Grep, Edit, AskUserQuestion

run — Run a Reboot Application

Bring an existing Reboot application up locally. This skill is the single canonical "start the app" procedure: it figures out what kind of app the project is, makes sure dependencies and secrets are ready, and launches every process the app needs.

Use it whenever the user wants to run, start, restart, or "bring up" an existing Reboot app — most commonly at the start of a fresh session, where no processes and no exported environment survive from last time.

This skill runs an app; it does not build or modify one. To build, see the chat-app skill and the web-app skill — those skills defer here for their "run the app" step.

Step 1 — Locate the project

Work in the directory the user named, or the current directory. The project root is the directory that contains .rbtrc. If there is no .rbtrc anywhere obvious, ask the user where the app is. Every command below runs from the project root.

Step 2 — Detect the app type

A Reboot project is one of two kinds. Decide using these signals, strongest first.

MCP Chat App — any of:

mcp_servers.json exists in the project root.
An API file under api/ uses mcp=Tool(), mcp=None, or UI( (the UI() method type).
.rbtrc has a dev run --default-config=hmr line together with a dev run:hmr --mcp-frontend-host=... line.
The frontend uses the nested web/ui/<name>/index.html layout.

Web App — all of:

No mcp_servers.json.
No mcp= / UI( anywhere under api/.
A single SPA entry at web/index.html (top of web/, not under web/ui/).

If the signals genuinely conflict, or none match, ask the user ("Is this an MCP Chat App or a standalone Web App?"). Do not guess — the app type changes whether the setup wizard is opened.

Step 3 — Dependencies

From the project root:

Backend: if .venv/ is missing, run uv sync.
Frontend: if web/node_modules/ is missing, run cd web && npm install.

Step 4 — Secrets: the git-ignored env file

Reboot apps read secrets from os.environ. rbt dev run loads them from an env file via its --env-file flag, configured once in .rbtrc. Set this up before starting the backend:

Find the required variables. Grep the backend for os.environ[...], os.environ.get(...), and os.getenv(...), and check main.py for Application(oauth=...) provider credentials. Every name found is a variable the app needs.
Make sure .rbtrc references the env file. It must contain the line dev run --env-file=.env. If it does not, add it.
Make sure .env is git-ignored. .env holds secrets and must never be committed. Check .gitignore at the project root for a line that ignores .env; if there is none, add .env to .gitignore (creating the file if it does not exist). Do this before writing any secret into .env.
Fill .env. Write standard .env KEY=VALUE lines — e.g. ANTHROPIC_API_KEY=sk-ant-.... For every required variable not already a line in .env (and not already exported in the environment), ask the user for the value and write it in. Never start the backend with a required variable missing — the app fails at boot or on first use, and the failure is hard to read.

The full secrets story — dev vs. Reboot Cloud — is in python/references/lifecycle-secrets.md.

Step 5 — Start the processes

Run each process in its own background shell, from the project root.

Backend — both app types

uv run rbt dev run --no-chaos

--env-file=.env in .rbtrc loads the secrets into the process; --no-chaos disables the Chaos Monkey, a useful bug-finder that is confusing to a developer who cannot see the backend terminal.

Frontend — both app types

cd web && npm run dev

Setup wizard — MCP Chat Apps only

An MCP Chat App's backend serves an interactive setup wizard at its root URL (http://localhost:9991) — a browser page that walks the user through connecting the app to an MCP client (such as MCPJam: picking a client, copying the /mcp endpoint, completing the OAuth handshake). It is the natural starting point — and the place the user launches MCPJam from, if they pick it — so open it.

Once the backend logs show it is serving traffic, do two things:

Tell the user the wizard exists and what it's for — e.g. "Setup wizard (connect an MCP client) at http://localhost:9991".

Open it once in the browser, best-effort:

"$BROWSER" http://localhost:9991 || xdg-open http://localhost:9991 || \
  python3 -m webbrowser http://localhost:9991

Open the wizard exactly once, at first startup — never on reloads. The backend runs under --watch and reprints its "serving traffic" banner every time it hot-reloads on a code change; re-opening a browser tab on each reload would be hostile. Because you open it as a one-shot step during initial startup (not from a loop that watches for the backend coming back up), this is naturally satisfied — just don't add any reload-driven re-open.

Skip this only for a Web App. A Web App has no MCP surface, so no wizard is served and there's nothing to connect — don't announce or open it. Every other app here is an MCP app, and the wizard is how you point a client at it, so open it even for a tools-only app with no UI() methods: connecting MCPJam or Claude through the wizard is exactly how the user tries those MCP tools out.

MCPJam inspector — on demand, never during startup

Do not start the MCPJam inspector as part of bringing the app up. MCPJam is just one of the MCP clients the setup wizard offers (alongside Claude and ChatGPT), so starting it is only relevant once the user picks MCPJam in the wizard. When they do, the wizard's MCPJam step shows the exact launch command — pointed at the app's /mcp endpoint with OAuth — for the user to run from their own terminal:

npx @mcpjam/inspector@2.9.3 --url http://localhost:9991/mcp --oauth

Leave the launch to the wizard. Only run it yourself if the user explicitly asks you to, and then use the plugin's mcpjam-inspector shim (it pins the version and passes --no-open so it does not pop a browser tab — you surface the URL instead):

mcpjam-inspector --url http://localhost:9991/mcp --oauth

Either way the inspector binds the fixed port 6274; its launcher orphans the server on SIGTERM, so the plugin reaps whatever is on 6274 when the agent session ends. Claude Code does this automatically via a SessionEnd hook; Codex has no session-end event, so see the README for how cleanup is handled there.

Step 6 — Hand off

Confirm every process is up from its logs, then give the user:

the application's own inspect-page URL;
for a Chat App — the setup-wizard URL (http://localhost:9991, already opened for them, for connecting an MCP client) and a first prompt to try (e.g. "Create a new todo list and show it to me"). Don't hand over an MCPJam URL — MCPJam isn't running, and only starts if the user picks it in the wizard (see the on-demand step above);
for a Web App — the frontend dev-server URL and a first page to open.

Always start every process the app needs. A Chat App needs backend and frontend; a Web App needs the same. (MCPJam is not in this set — it is launched on demand from the wizard, only if the user picks it.) The app is not usable until both are up, so do not stop after one.