Build on Floom.

What is Floom

Floom runs AI workers on a loop: small, autonomous programs that do a real job (clean an inbox, draft follow-ups, screen candidates) on a schedule, on a trigger, or on demand. Every worker runs in an isolated sandbox, draws on your company brain, calls your connected tools, and holds anything outward-facing for approval.

This is the developer reference for Floom Cloud. Everything you can do in the dashboard you can also do programmatically: through the CLI, any MCP client, or the REST API. All three speak to the same backend and the same workspace data, so you can mix them freely.

Three ways to build

Pick the surface that fits where you work. They cover the same core operations and share one backend; they mainly differ in ergonomics and how much they wrap for you (polling, streaming, auth).

Quickstart

The fastest path for Claude Code, Cursor, and other agent clients is MCP install. It targets hosted Floom Cloud by default, starts browser login only if you are not already logged in, and writes the client config for the active workspace.

Prefer raw HTTP? Mint a personal access token in the dashboard (Settings → API tokens) or with floom, then call the API directly. The token carries your workspace, so most requests need nothing else.

curl https://workeros-api.floom.dev/api/workers \
  -H "x-floom-token: floom_xxx"

Hosted vs self-hosted

Most users should use Floom Cloud: Floom hosts the API, sandbox compute, model/runtime infrastructure, storage, OAuth connections, and workspace auth. You do not need to clone the open-source repo, edit a local .env, or provide your own E2B_API_KEY just to use the hosted product.

• Hosted Cloud: use floom mcp install, floom login, the dashboard, or the Cloud REST API at https://workeros-api.floom.dev.
• Self-hosted: clone floomhq/floom, run your own API, configure local/server.env secrets, then opt in with floom login --local or WORKEROS_API_BASE.

Base URLs

The REST surface is the engine API mounted under several prefixes for client convenience: /workers, /api/workers, and /v1/workers are the same endpoint. This reference uses the /api prefix throughout.

Core concepts

• Worker: a job that runs on a loop. A bundle of worker.yml (the contract: trigger, inputs, tools, approval rules) plus run.py / SKILL.md code. Versioned in git. See the worker.yml reference.
• Run: one execution of a worker. Has a status, logs, outputs, artifacts, and a transcript; may pause for an approval.
• Context (brain): a pack of files (SOPs, pricing, datasets) a worker reads at run time. Large data lives here, not in the worker bundle.
• Connection: an authorized third-party account (Gmail, Slack, GitHub via Composio) or a custom MCP server a worker can call.
• Secret: an encrypted credential (API key, token) injected into a worker’s sandbox by name.
• Approval: a hold placed on an outward-facing action until a human approves or rejects it.
• Workspace: the tenant boundary. Members share workers, brain, connections, and the run record.