floom

The production layer for AI scripts.

Auto-generated UI from type hints. Shareable link. Built-in storage. Self-hosted with Docker.

---

Demo

Quick Start

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. The API runs on localhost:3001. Encryption key is auto-generated and persisted in the floom-data volume. Paste this:

from floom import app

@app.action
def greet(name: str) -> dict:
    return {"message": f"Hello, {name}!"}

Hit "Go Live." Share the link. That's it.

Clone and run locally

git clone https://github.com/floomhq/floom
cd floom
npm run setup:local
npm install

Self-host path:

docker-compose up --build

Manual local dev path:

# Terminal 1
cd services/control-plane && npm run dev

# Terminal 2
npm run dev:local

Open http://localhost:3000. The local API should answer on http://localhost:3001/health.

Three Copy-Paste Apps

• Greeting app: start with the snippet in Quick Start
• Visit counter with memory: examples/visit-counter/main.py
• Invoice generator: examples/invoice-generator/main.py

See all examples in examples/README.md.

How It Works

1. You write a Python function with type hints
2. floom extracts the schema (OpenAPI)
3. floom generates a web form from the schema
4. floom runs the function in a Docker sandbox
5. Anyone with the link can use it

Paste Raw Scripts (AI Smart Ingest)

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 GEMINI_API_KEY set, floom uses AI to:

• Detect city as a form input with "Berlin" as the default
• Identify requests as a dependency
• Wrap the script in a callable function
• Name the app "Weather Checker"

Without the key, raw scripts still deploy and run, but hardcoded values won't become form inputs. Add type hints to your functions for the same effect without AI:

def run(city: str = "Berlin") -> dict:
    ...

Set up: add GEMINI_API_KEY to your .env file. Get a free key.

Your App Can Remember Things

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}"}

No database setup. Built-in key-value storage.

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()

---

Self-Hosting

git clone https://github.com/floomhq/floom
cd floom
npm run setup:local
docker-compose up --build

setup:local generates the encryption key and .env file. That starts the control plane API on localhost:3001 with SQLite and Docker sandboxing. For the all-in-one web + API container, use the Quick Start command above.

Defaults

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

Environment Variables

Variable	Required	Default	Description
MASTER_ENCRYPTION_KEY	No	Auto-generated	32-byte base64 key for secrets encryption. Auto-generated and persisted in /data/.master-key if not set.
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)
GEMINI_API_KEY	No		Enables AI smart ingest for raw scripts (see below)

See .env.example for the full list.

Cloud Mode

floom supports a cloud deployment mode (Langfuse model: one codebase, features gated by env vars).

To enable cloud features (Supabase auth, billing, route guards):

1. Set FLOOM_MODE=cloud in your .env
2. Set NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY
3. Run Supabase migrations: supabase db push (migrations in supabase/migrations/)
4. Optionally set SUPABASE_SERVICE_ROLE_KEY for server-side operations

When these env vars are not set, the app runs in full OSS mode with no auth, no billing, and no route guards.

---

For Developers

Python SDK

from floom import app, remember, forget, storage

# Mark functions as actions
@app.action
def my_func(x: int) -> dict:
    return {"result": x * 2}

# Custom action name
@app.action(name="custom_name")
def another_func(y: str) -> dict:
    return {"greeting": f"Hello, {y}!"}

# Full storage API
storage.set("config", {"theme": "dark"})
data = storage.get("config")        # {"theme": "dark"}
storage.get("missing", default=0)   # 0
storage.list()                       # ["config"]
storage.delete("config")

CLI

npm install -g @floomhq/cli

# Deploy a Python file
floom deploy my-app.py --name "My App"

# Run an action (returns JSON to stdout)
floom run greet name=world

# List your apps
floom list

# View logs
floom logs

# Check local setup
floom doctor

# Manage storage
floom storage list
floom storage get <key>
floom storage set <key> <value>

# Share your app
floom share create <endpoint_id>

# Set up MCP for AI agents
floom setup-mcp

For AI Agents

MCP Setup (one command):

npx @floomhq/cli setup-mcp

Prints the config block. Paste it into your MCP config and agents get tools to deploy, run, and manage apps.

Per-app REST API (no polling, no IDs):

# Discover what an app can do
curl http://localhost:3001/v1/apps/my-app

# Call an action directly
curl -X POST http://localhost:3001/v1/apps/my-app/greet \
  -H 'Content-Type: application/json' \
  -d '{"name": "world"}'
# Returns: {"status":"success","result":{"message":"Hello, world!"},"duration_ms":1200}

CLI for agents:

floom deploy main.py --name my-app
floom run greet name=world          # Returns result JSON to stdout

API Reference

All routes are under /v1/. Full OpenAPI spec at /v1/openapi.json. Human-friendly API docs landing: /docs.

Per-app API (agent-friendly): GET /v1/apps/:slug (discover actions), POST /v1/apps/:slug/:action (execute synchronously)

Apps: GET /v1/projects, POST /v1/projects, GET /v1/projects/:id, PATCH /v1/projects/:id, DELETE /v1/projects/:id

Deploy: POST /v1/projects/:id/deploy, GET /v1/projects/:id/deploy/status

Runs: POST /v1/runs, GET /v1/runs/:id

Secrets: POST /v1/projects/:id/secrets, GET /v1/projects/:id/secrets

Storage: GET /v1/projects/:id/storage, PUT /v1/projects/:id/storage/:key, GET /v1/projects/:id/storage/:key

Templates: GET /v1/templates, GET /v1/templates/:id, POST /v1/templates/:id/create

Architecture

Function (type hints) -> OpenAPI Schema -> Auto-generated Form -> Shareable Link
                              |
                         Docker Sandbox
                              |
                           SQLite

floom/
+-- apps/web/                  # Next.js web app (paste, deploy, run, share)
+-- packages/
|   +-- cli/                   # CLI: floom deploy, floom list, ...
|   +-- client/                # TypeScript API client
|   +-- mcp-server/            # MCP tools for AI agents
|   +-- openapi-form/          # Auto-generates web forms from functions
|   +-- shared/                # TypeScript types and contracts
|   +-- ui/                    # Shared React components
+-- services/
|   +-- control-plane/         # Hono.js API server
|   +-- runner/                # Python execution runtime + SDK

Development

npm install
npm run build   # Build all packages
npm test        # Run TypeScript + Python tests
npm run test:ts # Run TypeScript workspace tests only

Why teams pick floom

• Turn Python functions into usable apps without building frontend forms by hand
• Keep execution isolated with Docker sandboxing
• Keep state simple with built-in remember() storage
• Share links instantly for demos, internal tools, and experiments

Standards-compatible workflows

floom works with standard API and browser tooling:

• OpenAPI contract at GET /v1/openapi.json
• Docs landing at GET /docs
• Browser automation friendly routes (/new, /p/:id, /s/:id)
• CLI + API parity for scripting and CI

Common pairings:

• Postman/Insomnia for API exploration
• Playwright/browser-use style flows for UI automation
• cURL scripts for smoke checks and CI gates

See docs/INTEGRATIONS.md for concrete examples.

Launch Kit

• 2-minute onboarding guide: docs/LAUNCH_FIRST_APP.md
• Distribution copy for launch channels: docs/LAUNCH_KIT.md
• PRR scorecard and go/no-go checks: docs/PRR_SCORECARD.md

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT. See LICENSE.