io.github.floomhq/floom
Deploy Python functions as web apps with auto-generated UI, REST API, and shareable links.
Ask AI about io.github.floomhq/floom
Powered by Claude Β· Grounded in docs
I know everything about io.github.floomhq/floom. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Floom
The protocol + runtime for agentic work.
Vibe-coding speed. Production-grade safety.
Build agents, workflows, and scripts with AI. Floom deploys them as an MCP server, HTTP API, and shareable web form. Open source.
Point Floom at an OpenAPI spec. In seconds you get a web form, an MCP server an agent can call, and an HTTP endpoint. All from the same manifest, all with auth, rate limits, secret injection, and a shareable output page.
What it does
- One manifest, three surfaces. Web form at
/p/:slug, MCP server at/mcp/app/:slug, HTTP endpoint at/api/:slug/run. - Two ingest modes. Proxied (wrap an existing API) or hosted (Floom runs your Docker container).
- Production layer included. Bearer/API-key auth, per-operation rate limits, secret injection, run history, shareable result URLs.
- Agent-native. Every app exposes MCP tools out of the box. Four MCP admin tools (
ingest_app,list_apps,search_apps,get_app) let an agent add new apps over MCP.
Who it's for
- Vibecoder creators shipping weekend apps (OpenDraft, OpenPaper shape). Paste an OpenAPI URL, publish a shareable page, get an MCP tool your friends can install.
- Biz users running internal tooling and productivity apps. Wrap a Stripe-style API in a form your ops team can fill out, with runs logged and outputs rendered cleanly.
Two equal ICPs. Two CTAs side by side. Two dashboards (/me for consumers, /creator for publishers).
How it works
OpenAPI spec βββΆ Floom manifest βββΆ 3 surfaces
ββ Web form + output page (/p/:slug)
ββ MCP server (/mcp/app/:slug)
ββ HTTP endpoint (/api/:slug/run)
Floom reads each OpenAPI operation, turns its parameters into a form field or MCP tool input, injects secrets at runtime, and renders the response. No glue code.
Β
Quickstart (cloud)
- Sign in at floom.dev.
- Paste an OpenAPI spec URL at floom.dev/build.
- Publish. Share the
/p/:slugURL, or install the MCP server in your agent.
Self-host (60 seconds)
cat > apps.yaml <<'EOF'
apps:
- slug: resend
type: proxied
openapi_spec_url: https://raw.githubusercontent.com/resend/resend-openapi/main/resend.yaml
base_url: https://api.resend.com
auth: bearer
secrets: [RESEND_API_KEY]
display_name: Resend
description: "Transactional email API."
EOF
docker run -d --name floom \
-p 3051:3051 \
-v floom_data:/data \
-v "$(pwd)/apps.yaml:/app/config/apps.yaml:ro" \
-e FLOOM_APPS_CONFIG=/app/config/apps.yaml \
-e RESEND_API_KEY=re_... \
ghcr.io/floomhq/floom-monorepo:v0.4.0-mvp.4
Then open http://localhost:3051/p/resend, or point your agent at http://localhost:3051/mcp/app/resend.
Auth modes
Floom ships with two independent auth layers and they share one header. Read this before you deploy:
FLOOM_AUTH_TOKENis an operator-wide kill switch. When set, every/api/*,/mcp/*,/p/*request must presentAuthorization: Bearer <token>. Use it for a solo box or a CI/staging guard.FLOOM_CLOUD_MODE=trueturns on Better Auth so real users sign in and their API keys ride the sameAuthorization: Bearer <key>header.
A single header can only carry one token. Enabling both on the same deployment locks your signed-in users out of the API. Pick one per deployment β see the comment block above FLOOM_AUTH_TOKEN in docker/.env.example for the full breakdown.
Full guide: docs/SELF_HOST.md Β· Protocol spec: spec/protocol.md
The manifest
Two shapes, same surfaces.
# Proxied β wrap an existing API
name: stripe
type: proxied
openapi_spec_url: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
base_url: https://api.stripe.com
auth: bearer
secrets: [STRIPE_SECRET_KEY]
# Hosted β Floom runs your container
name: my-app
type: hosted
runtime: python3.12
openapi_spec: ./openapi.yaml
build: pip install .
run: uvicorn my_app.server:app --port 8000
See example manifests under examples/.
Repo layout
apps/webβ floom.dev web surface (React, form + output renderer)apps/serverβ backend (Hono + SQLite + Docker runner)packages/rendererβ@floom/renderer, default + custom output/input renderer libraryspec/protocol.mdβ Floom Protocol specexamples/β example manifests you can copy to register your own app
Development
pnpm install
pnpm dev
Runs the web app on :5173 and the server on :3051 with hot reload.
Roadmap
See docs/ROADMAP.md for priorities. The v0.4 line is OpenAPI ingest, secret policies, per-app rate limits, and MCP admin tools; everything else is parked until those are battle-tested.
Community
- Support and usage questions: see SUPPORT.md
- Security reports: see SECURITY.md
- Contribute: see CONTRIBUTING.md
Built in SF by @federicodeponte.
License
MIT. See LICENSE.
