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.
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.
| 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.
| 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 |
- 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.
| 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 |
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.shWindows 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.ps1Requires 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.
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"]
- Workers — folders under
workers/<name>/withworker.ymlplus 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.
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.
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
- Getting started — why Floom exists, first run, first worker, safe self-hosting checklist.
- Authoring workers — full
worker.ymlschema, 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.
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:mcpTo report a vulnerability, follow SECURITY.md and report it privately rather than opening a public issue.
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.