Demo

What it does

Deploy vs run (ICP): Deploy means “send your app to a Floom control plane” (hosted cloud or your self-host). Run executes in Floom’s sandbox on that side, not on the user’s laptop. Same low-friction idea as paste-to-publish tools (for example static aired.sh), but floom ships runnable Python, REST, generated forms, and secrets, not only static HTML.

The aha in one beat: you write one Python function with type hints. floom gives one live app: a generated form, a REST surface, a share link, and MCP tools that call the same actions. No duplicate logic between browser and IDE.

Who uses what: Cursor and Claude Code (and similar) integrate via MCP (deploy, run, secrets). Functionality is agent- and API-first: behavior lives in the control plane and is exposed through REST, MCP, and CLI. The web UI is a thin wrapper on that same API: paste a script, use generated forms, run, and share. OpenAPI is generated from your Python; you do not hand-author it for Floom apps.

You write a Python function with type hints:

# main.py
from floom import app

@app.action
def generate_invoice(client: str, amount: float, due_date: str):
    pdf = create_pdf(client, amount)
    return {"url": pdf.url}

# floom.yaml (optional - floom auto-detects from type hints)
name: invoicer
version: 1
endpoints:
  POST /generate_invoice:
    summary: Create an invoice PDF
    inputs:
      type: object
      required: [client, amount, due_date]
      properties:
        client: { type: string, example: "Acme Corp" }
        amount: { type: number, example: 1500 }
        due_date: { type: string, example: "2026-05-01" }

floom gives you:

• A web form with fields auto-generated from your type hints
• A REST API with OpenAPI spec
• A permanent share link anyone can use (no expiry)
• MCP tools for AI agent integration
• Docker sandboxing for isolated execution

No Dockerfile. No frontend code. No deploy config. See BUILDING.md for the full protocol.

Quick Start

Using Floom cloud: create an account on floom.dev, paste or deploy from the UI, or configure MCP with your cloud API base URL as FLOOM_URL and your API key (see Agent guide). You do not need the Docker command below.

Self-host (Docker):

docker run -p 3000:3000 -p 3001:3001 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/floom-workspaces:/tmp/floom-workspaces \
  -v /tmp/floom-storage:/tmp/floom-storage \
  -v floom-data:/data \
  ghcr.io/floomhq/floom

Open localhost:3000. Paste a Python function. Hit "Go Live."

How type hints become UI

Built-in storage

Your app can remember things across runs. No database setup.

from floom import app, remember

@app.action
def count_visits(name: str) -> dict:
    visits = (remember("visits") or 0) + 1
    remember("visits", visits)
    return {"message": f"Hello {name}! Visit #{visits}"}

Paste raw scripts

Got code from ChatGPT with no functions or type hints? floom can handle it.

import requests
city = "Berlin"
response = requests.get(f"https://wttr.in/{city}?format=j1")
data = response.json()
print(f"Temperature in {city}: {data['current_condition'][0]['temp_C']}°C")

With FLOOM_AI_ENHANCE_INGEST=1 and GEMINI_API_KEY set, floom can use Google Gemini after mechanical extraction to detect city as a form input, identify requests as a dependency, and wrap the script in a callable function. By default ingest is mechanical only. Get a free key.

Examples

For AI agents

floom is built for AI-assisted workflows. Every app gets an OpenAPI spec, and the MCP server gives agents direct access.

MCP setup (Claude Code, Cursor, Windsurf)

One command adds floom to your MCP config:

npx @floomhq/cli setup-mcp

Or add manually to your MCP config:

{
  "mcpServers": {
    "floom": {
      "command": "npx",
      "args": ["-y", "@floomhq/mcp-server"],
      "env": { "FLOOM_URL": "http://localhost:3001" }
    }
  }
}

CLI

npm install -g @floomhq/cli
floom deploy app.py --name "My App"
floom run greet name=world
floom doctor    # verify setup

Common patterns

• Deploy with HTTP calls: set config: { network: true } in deploy, or RUNNER_NETWORK=bridge on the server
• Deploy with secrets: use the manage_secrets tool (persistent), or pass secrets in run (one-time)
• Discover actions: curl http://localhost:3001/v1/apps/my-app
• Call directly: curl -X POST http://localhost:3001/v1/apps/my-app/greet -H 'Content-Type: application/json' -d '{"name": "world"}'

Resources

• Documentation index (launch, architecture, guides)
• Agent workflow guide
• LLM-readable reference

Self-hosting

Docker (recommended)

The Quick Start command above runs the all-in-one container. Encryption key is auto-generated and persisted in the floom-data volume.

From source

git clone https://github.com/floomhq/floom
cd floom
npm run setup:local    # generates encryption key + .env
npm install
docker-compose up --build

• Web UI: http://localhost:3000
• API: http://localhost:3001
• Health: http://localhost:3001/health

See .env.example for the full list.

CLI

npm install -g @floomhq/cli

floom init my-app                          # scaffold main.py + floom.yaml + requirements.txt
floom deploy .                             # deploy current directory
floom validate                             # check floom.yaml + main.py consistency
floom run greet name=world                 # run an action
floom list                                 # list apps
floom logs                                 # view run logs
floom doctor                               # verify setup
floom secrets set API_KEY sk-...           # manage API keys
floom storage list                         # persistent storage
floom share create <endpoint_id>           # create share link
floom setup-mcp                            # MCP config for Claude/Cursor

Architecture

High-level flow:

Python function (type hints)
        |
   OpenAPI schema extraction
        |
   +----+----+
   |         |
 Web form   REST API
   |         |
   Docker sandbox (isolated execution)
        |
     SQLite (state + storage)

Details (single sources of truth, so this README does not duplicate them):

• docs/ARCHITECTURE.md — v0 surface, Docker-only compute, /v1 vs legacy API
• docs/CODEBASE_TOUR.md — directory layout, projects/runs/secrets, contributor patterns

Development

npm install
npm run build   # Build all packages
npm test        # Run all tests

Known Limitations

• Single instance only: The control plane uses in-memory state for run progress and deploy tracking. Running multiple control plane instances will cause state to be lost between them. A Redis-backed implementation is planned for multi-instance deployments.
• Artifact serving: Artifacts larger than 1MB are not served inline. S3-backed artifact storage is planned for production use.

Support

• Bugs and questions: GitHub Issues
• Cloud (floom.dev): [email protected]

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.