Floom

Create AI workers that run on schedules, webhooks, and tool calls.

Write a worker in plain English, connect tools like Slack, Gmail, GitHub, or Stripe, and let it run in a sandbox with approvals, logs, outputs, and every run on the record.

Get started · Try the hosted version · Read the docs

---

Most "AI automation" is a chat window you babysit, or a no-code graph that bills you per task and can't be audited. Floom is the missing middle: a real runtime where a worker is a folder you can read, it runs without you watching — script workers isolated in a sandbox — and every execution leaves logs, outputs, tool calls, approvals, and a replay you can trust.

What a worker looks like

A worker is a folder. Describe what it should do in plain English (SKILL.md) or hand it a script (run.py), declare its tools and trigger in worker.yml, and Floom runs it.

# workers/github-digest/worker.yml  (abbreviated)
name: github-digest
description: "Every morning at 9am, send a digest of unread GitHub PRs and open issues."
exec:
  entry: SKILL.md          # plain-English agent worker; or run.py for a script
trigger:
  type: schedule
  cron: "0 9 * * *"        # also: manual, webhook, Composio event
connections:
  - app: github            # the only tools this worker is allowed to call
    allowed_tools: [GITHUB_FIND_PULL_REQUESTS, GITHUB_LIST_ASSIGNED_ISSUES]

<!-- workers/github-digest/SKILL.md -->
You are a GitHub assistant generating a daily PR + issues digest.
Fetch the user's open PRs and assigned issues, compile a markdown digest
with Action items, and finish_with_outputs({ "digest": "<markdown>" }).

It runs at 9am, calls only the two GitHub tools it declared, and writes digest.md to a run you can open, replay, or roll back:

run 7f3a · github-digest · finished 09:00:04 · 2 tool calls · output: digest.md
  ✓ GITHUB_FIND_PULL_REQUESTS    q="is:open is:pr author:@me"   → 4 PRs
  ✓ GITHUB_LIST_ASSIGNED_ISSUES  state=open                     → 2 issues
  → out/digest.md (text/markdown)   [open · replay · rollback]

The full manifest adds schema_version, title, version, and declared outputs. See workers/ for runnable examples and the agent cookbook.

Two kinds of worker

| | runs in | host isolation | tools | side effects | |---|---|---|---|---| | Script (run.py / .sh / .js) | E2B sandbox microVM | isolated filesystem, env & process; platform secrets withheld | sandbox + declared connections | approval gate when declared | | Agent (SKILL.md) | AgentDriver in the API process (trusted bundles only) | not microVM-isolated by policy | declared connections, allow-listed | approval gate when declared |

Sandboxes allow public network egress by default and block private/internal ranges; a stricter allowlist is optional. Full trust model: ARCHITECTURE.md.

At a glance

| | | |:---|:---| | What it is | Self-hosted runtime to create, run, and supervise background AI workers | | Best for | Recurring agent work: inbox triage, digests, outreach drafting, enrichment, monitoring | | Worker types | Script (run.py/.sh/.js) and plain-English agent (SKILL.md) | | Isolation | Script workers run in E2B sandbox microVMs — isolated host filesystem, env & process; platform secrets withheld | | Triggers | Manual, schedule (cron), webhook, Composio event | | Safety | Human-in-the-loop approvals for side-effecting workers; tools allow-listed per worker | | On the record | Every run records logs, outputs, tool calls, approval state, replay + rollback | | Cost model | Floom adds no per-task fee — you pay E2B sandbox runtime (per second) plus your model/API provider usage | | Stack | Next.js + Tailwind UI · FastAPI + SQLite API · MCP server + CLI | | Runs on | Linux, macOS, Windows (Python 3.11+, Node 20+) | | License | Floom Source Available 1.0 · hosted version |

Who is this for?

Founders & operators turning recurring work (digests, triage, outreach) into workers that run themselves.
Engineers who want a real runtime — manifests, sandboxes, limits, approvals — not a prompt file and a cron job.
Teams who need every action allow-listed, approved, and replayable for audit.
Anyone burned by agents that ran a destructive command, leaked a secret, or claimed success with nothing on the record.

Why Floom

| | bare agent script | hosted task-metered automation (Zapier / Make) | Floom | |---|---|---|---| | Worker definition | ad-hoc prompt / code | visual graph, hard to diff | a folder: worker.yml + SKILL.md/run.py | | Isolation | runs on your host | vendor cloud, opaque | E2B sandbox microVM (script workers) | | Tool access | whatever it can reach | per-connector | declared + allow-listed per worker | | Side effects | fire immediately | no built-in approval gate | human approval gate (HITL) when declared | | Observability | scrollback, if any | per-step logs you can't replay | logs + tool calls + outputs + replay + rollback | | Cost | model tokens | per-task / per-execution fees | no per-task fee — runtime + provider usage | | Hosting | your host | vendor only | self-host, or hosted |

Quick start

Linux / macOS

git clone https://github.com/floomhq/floom.git
cd floom
./scripts/setup.sh
# edit apps/api/.env: add a model provider key and E2B_API_KEY
./scripts/dev.sh

Windows PowerShell

git clone https://github.com/floomhq/floom.git; cd floom
.\scripts\setup.ps1
# edit apps\api\.env: add a model provider key and E2B_API_KEY
.\scripts\dev.ps1

Requires Python 3.11+, Node.js 20+, Git, a model provider key, and an E2B key from e2b.dev. Open http://localhost:3000 and sign in — no auth secret for local dev, and the example workers are seeded on first boot.

Full setup, model providers, optional integrations, and the safe self-hosting checklist: docs/GETTING-STARTED.md. Common issues: docs/TROUBLESHOOTING.md.

Not ready to self-host? floom.dev is the hosted version — hire AI workers with no setup.

How a run works

flowchart LR
  Trigger["Trigger<br/>manual · schedule · webhook · Composio"] --> Worker["Worker<br/>worker.yml + SKILL.md / run.py"]
  Worker --> Runner{"Runner"}
  Runner -->|".py / .sh / .js"| Sandbox["E2B sandbox microVM<br/>isolated, secrets withheld"]
  Runner -->|"SKILL.md (agent)"| Driver["AgentDriver<br/>declared tools only"]
  Sandbox --> Side{"Side effect?"}
  Driver --> Side
  Side -->|yes| Approval["Human approval<br/>/approvals"]
  Side -->|no| Record
  Approval --> Record["Run record<br/>logs · tool calls · outputs · replay · rollback"]

Core concepts

Workers — folders under workers/<name>/ with worker.yml plus a script entrypoint (run.py) or an agent prompt (SKILL.md).
Runs — every execution records logs, outputs, tool calls, approval state, and replay/rollback context.
Contexts — reusable file bundles attached to workers as reference material; sensitive by default.
Approvals — side-effecting workers pause for a human decision before anything leaves the building.
Workspace history — workers, contexts, and settings versioned in a git-backed workspace for rollback.

Write your first worker in docs/GETTING-STARTED.md, then docs/AUTHORING.md for the full manifest and runtime contract.

How workers execute

Script workers (.py/.sh/.js) run in an E2B sandbox microVM by default: isolated dependencies, no host process access, contained resources. A bundle that dumps os.environ inside the sandbox sees only sandbox metadata — FLOOM_SECRET, provider keys, and E2B_API_KEY are all absent. Agent workers (SKILL.md) run through the API-hosted AgentDriver tool loop and are governed by their declared connections and the approval gate; the current single-tenant policy permits only trusted agent bundles on that path. There is no in-process local script runner. Full trust model: ARCHITECTURE.md.

Architecture

apps/web      Next.js + TypeScript + Tailwind + shadcn/ui
apps/api      FastAPI + SQLite + Pydantic
apps/mcp      MCP server + CLI
workers/      Worker folders (worker.yml + run.py or SKILL.md)
data/         SQLite DB + run artifacts

Docs

Getting started — why Floom exists, first run, first worker, safe self-hosting checklist.
Authoring workers — full worker.yml schema, execution modes, secrets, connections, triggers, approvals.
Agent cookbook — agent-assisted worker authoring recipes.
Architecture — runtime topology and the sandbox trust model. Read before filing security findings.
API overview — curated endpoint map; full reference at http://localhost:8000/docs.
Troubleshooting · Roadmap · Project history · v1.0.0 release notes
Licensing — what the Floom Source Available License allows and what needs a commercial agreement.

Contributing

Contributions are welcome. See CONTRIBUTING.md for local setup, the first-contribution map, and PR guidelines. Quick local checks from the repo root:

npm run test:api
npm run lint:web
npm run test:web
npm run test:mcp

Security

To report a vulnerability, follow SECURITY.md and report it privately rather than opening a public issue.

License

Floom Source Available License 1.0 © Floom contributors. Free for internal business use, non-commercial and personal use, building your own products or services, and consulting/integration work for permitted deployments. Offering Floom itself as a hosted service, managed platform, white-label product, or competing commercial service requires a separate commercial agreement.

floom