<div align="center">

floom

The production platform agents deploy to.

AI writes the code. floom puts it in production: live URL, REST API, web UI, and MCP tools in 45 seconds. Cloud: deploy runs on Floom’s servers — paste in the browser or let agents deploy via MCP. Self-host: run Docker when you want Floom on your own infra. Agents always target whatever FLOOM_URL is set to.

Add to your README:

[![Deploy on floom](https://floom.dev/badge.svg)](https://floom.dev/deploy)

Add to Claude Code (global skill):

curl -fsSL https://floom.dev/skill.md -o ~/.claude/skills/floom.md

Deploy from CI:

- uses: floomhq/deploy-action@v1
  with:
    api-key: ${{ secrets.FLOOM_API_KEY }}

Website · Docs · Examples · llms.txt · OSS hub (target): oss.floom.dev (live when DNS and deploy are wired; until then use Docker in this README)

</div>

---

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

| Python type | Generated UI | |-------------|-------------| | str | Text input | | int | Number input | | float | Number input (decimal) | | bool | Checkbox | | Literal["a","b"] | Dropdown select | | dict | JSON editor | | Default values | Pre-filled placeholders |

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

| Example | What it does | |---------|-------------| | Invoice Generator | Create invoices with automatic tax calculation | | Text Analyzer | Count words, find common phrases, detect sentiment | | Unit Converter | Convert temperatures and distances between units | | Visit Counter | Greet visitors and track counts with remember() |

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

<details> <summary><strong>Environment variables</strong></summary>

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MASTER_ENCRYPTION_KEY | No | Auto-generated | 32-byte base64 key for secrets encryption | | COMPUTE_BACKEND | No | docker | docker for self-hosted | | PORT | No | 3001 | Server port | | API_KEY | No | | Bearer token to protect API | | RUNNER_IMAGE | No | floom-runner:latest | Docker image for code execution | | RUNNER_MEMORY | No | 512m | Memory limit per container | | RUNNER_CPUS | No | 1 | CPU limit per container | | RUNNER_NETWORK | No | none | Network mode (none for isolation) | | FLOOM_AI_ENHANCE_INGEST | No | (off) | Set to 1 or true to opt in to Gemini post-extract ingest | | GEMINI_API_KEY | No | | Required only if FLOOM_AI_ENHANCE_INGEST is enabled |

See .env.example for the full list.

</details>

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 —