Skip to content

GETTING-STARTED.md

Latest commit

 

History

History
360 lines (283 loc) · 11.2 KB

GETTING-STARTED.md

File metadata and controls

360 lines (283 loc) · 11.2 KB
Raw

Getting started

Floom is an open-source runtime for AI workers: small, versioned worker bundles that can read inputs, use approved tools/connections, run in a sandbox, and leave behind logs, outputs, approvals, and history.

Use it when a team has repeatable knowledge-work workflows that need more control than a prompt in a chat window: scheduled reports, inbox triage, CSV enrichment, CRM updates, approval-gated actions, research briefs, or internal ops automation.

What you get locally

This page is for the local/self-hosted runtime. If you only want to use hosted Floom Cloud from Claude Code, Cursor, the CLI, or the dashboard, start with:

npx -y @floomhq/floom mcp install --target claude

Hosted Cloud does not require cloning this repo, editing .env, or supplying your own model-provider key or E2B_API_KEY; those are local/self-hosted runtime requirements. The local setup runs the same core pieces used by hosted deployments:

  • FastAPI backend with SQLite persistence.
  • Next.js web app.
  • E2B sandbox execution for script workers.
  • Agent-mode workers powered by the configured LLM provider.
  • Local workspace data, contexts, run logs, approvals, and version history.

Hosted-only concerns such as commercial billing, managed enterprise SSO, and SOC 2 evidence collection live outside the open-source runtime. This repo provides the core runtime and local/self-hosted path.

Before operating a public hosted deployment, review the data and legal boundaries in DATA-RETENTION.md. Public deployments should have explicit Terms/Privacy acceptance and provider-side spend alerts in addition to Floom's run-dispatch caps.

1. Run the local app

Prerequisites:

  • Python 3.11 or newer.
  • Node.js 20 or newer.
  • Git.
  • Model-provider credentials: AWS credentials for the Bedrock worker-agent default, or an explicit OpenAI/other-provider key when configured.
  • E2B_API_KEY for sandboxed script-worker execution.

Linux / macOS:

./scripts/setup.sh
# edit apps/api/.env and add E2B_API_KEY plus your model provider config
./scripts/dev.sh

Windows PowerShell:

.\scripts\setup.ps1
# edit apps\api\.env and add E2B_API_KEY plus your model provider config
.\scripts\dev.ps1

Open http://localhost:3000. The API listens on http://localhost:8000.

2. Manual setup and configuration

The scripts above are the recommended path. Use the manual steps only when you need to debug one side of the stack.

Backend:

cd apps/api
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env and add E2B_API_KEY plus your model provider config
python main.py

Windows PowerShell:

cd apps\api
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
Copy-Item .env.example .env
# edit .env and add E2B_API_KEY plus your model provider config
python main.py

Frontend:

cd apps/web
cp .env.example .env
npm install
npm run dev

Start the backend with python main.py during development. Avoid bare uvicorn main:app --reload; the checked-in entry point excludes runtime artifact directories from reload watching.

Model providers

Worker agents default to Bedrock on hosted deployments. To use another provider, set the role-specific model variables to a litellm model id and provide that provider's credentials.

Env var Role Default
WORKEROS_WORKER_AGENT_MODEL tool-calling worker agents bedrock/us.anthropic.claude-sonnet-4-6
WORKEROS_AGENT_FALLBACK_MODEL ordered agent fallbacks for capacity and quota failures bedrock/us.anthropic.claude-sonnet-4-6
WORKEROS_CHAT_MODEL Emily chat assistant gpt-5.4-mini
WORKEROS_CHAT_MODEL_FALLBACK Emily fallback for quota/auth failures unset
WORKEROS_CODEGEN_MODEL worker codegen, draft, and repair gpt-5.5
WORKEROS_SUGGEST_MODEL worker-edit conflict check codegen model

Example Bedrock configuration:

WORKEROS_WORKER_AGENT_MODEL=bedrock/us.anthropic.claude-sonnet-4-6
WORKEROS_CHAT_MODEL=bedrock/us.anthropic.claude-sonnet-4-6
WORKEROS_CHAT_MODEL_FALLBACK=gpt-5.4-mini
WORKEROS_CODEGEN_MODEL=bedrock/us.anthropic.claude-sonnet-4-6
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION_NAME=us-west-2

For ordered cross-provider worker fallback, provide a comma-separated chain. A single model remains valid for backwards compatibility. Floom skips duplicate models, same-provider transitions, and providers without configured credentials.

WORKEROS_AGENT_FALLBACK_MODEL=gemini/gemini-3.5-flash,openai/gpt-5.5

Optional OpenAI configuration:

WORKEROS_WORKER_AGENT_MODEL=gpt-5.5
WORKEROS_CHAT_MODEL=gpt-5.4-mini
WORKEROS_CODEGEN_MODEL=gpt-5.5
OPENAI_API_KEY=...

Other litellm providers work the same way:

Provider Model id example Key
Anthropic anthropic/claude-sonnet-4-6 ANTHROPIC_API_KEY
Google Gemini gemini/gemini-2.5-pro GEMINI_API_KEY
Groq groq/llama-3.3-70b-versatile GROQ_API_KEY

For Gemini API-key failover, set GEMINI_API_KEY_FALLBACK (or GOOGLE_API_KEY_FALLBACK). Floom retries once with the fallback key when the primary Gemini key returns an auth, billing, quota, or rate-limit style failure.

Vertex AI Gemini uses Google Application Default Credentials instead of GEMINI_API_KEY. For local development, install from the normal requirements file, then set a Vertex model id and Google auth environment:

WORKEROS_WORKER_AGENT_MODEL=vertex_ai/gemini-3.5-flash
WORKEROS_CHAT_MODEL=vertex_ai/gemini-3.5-flash
WORKEROS_CODEGEN_MODEL=vertex_ai/gemini-3.5-flash
VERTEX_PROJECT=your-gcp-project
VERTEXAI_PROJECT=your-gcp-project
VERTEX_LOCATION=global
VERTEXAI_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/application-default-or-wif.json

If GOOGLE_APPLICATION_CREDENTIALS points at an AWS workload identity federation config, Google auth also needs AWS credentials and a region in the backend process environment:

AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-west-2
AWS_DEFAULT_REGION=us-west-2

Without those AWS variables, local machines may try the AWS instance metadata endpoint (169.254.169.254) and Vertex calls will fail before reaching Gemini.

Emily and web-search workers use a provider-agnostic web_search function tool. It defaults to DuckDuckGo; set SERPER_API_KEY for Google-quality results.

Optional configuration

  • FLOOM_SECRET: operator secret for API requests. Leave unset for local dev; set WORKEROS_SHARED_SECRET_ROLE=admin only when legacy admin-equivalent shared-secret access is required.
  • COMPOSIO_API_KEY and COMPOSIO_WEBHOOK_SIGNING_KEY: OAuth apps and triggers.
  • SLACK_CLIENT_ID and SLACK_CLIENT_SECRET: Slack integration.
  • WORKEROS_MAGIC_LINK_SECRET: HMAC key for magic sign-in links.
  • FLOOM_WORKERS_DIR and FLOOM_CONTEXTS_DIR: set both outside the source checkout to enable git-backed worker/context history.
  • WORKEROS_GIT_REMOTE: optional remote for workspace history.

Worker secrets are stored encrypted in .secrets.enc. For local git setups, back up ~/.config/workeros/secrets.key; losing it means existing encrypted secrets must be re-entered.

Version history

Workers, contexts, and workspace settings can be committed to a local git workspace. workers.versions and contexts.versions list commits; rollback restores a version by writing a new commit, so you can roll forward again.

The workspace git root is the parent of FLOOM_WORKERS_DIR. The engine refuses to commit history into its own source checkout, so point worker and context directories somewhere else:

FLOOM_WORKERS_DIR=~/.workeros/workers
FLOOM_CONTEXTS_DIR=~/.workeros/contexts

That shared parent becomes a local git repo with no remote. Set WORKEROS_GIT_REMOTE only if you want to push workspace history to your own git host.

3. Build your first worker

Create a folder:

workers/hello-worker/
  worker.yml
  run.py

workers/hello-worker/worker.yml:

schema_version: "0.3"
name: hello-worker
title: Hello Worker
description: Greets a person from an input.
version: 0.1.0
entrypoint: run.py
exec:
  command: python run.py
  runtime: python311
  runner: e2b
  inputs:
    - name: name
      kind: scalar
      type: string
      required: true
      label: Name
      default: world
  outputs:
    - name: greeting
      kind: file
      media_type: text/plain
      path: out/greeting.txt
      required: true
      label: Greeting

workers/hello-worker/run.py:

import json
from pathlib import Path

inputs = json.loads(Path("inputs.json").read_text(encoding="utf-8"))
name = inputs.get("name") or "world"

Path("out").mkdir(exist_ok=True)
Path("out/greeting.txt").write_text(f"Hello, {name}!\n", encoding="utf-8")
Path("result.json").write_text(
    json.dumps(
        {
            "status": "success",
            "outputs": {"greeting": "out/greeting.txt"},
            "artifacts": [],
            "error": None,
        }
    ),
    encoding="utf-8",
)

Reload workers in the UI or restart the dev server, then run Hello Worker from the Workers page.

For the full schema, agent workers, approvals, triggers, secrets, and connections, read AUTHORING.md.

CLI deploy loop

npm i -g @floomhq/floom
floom login --local
floom workers validate ./workers/<id>
floom workers push ./workers/<id>
floom run <id> --inputs-file inputs.json

floom login --local is intentionally local/self-hosted. For hosted Floom Cloud, use floom login or floom mcp install, which target https://workeros-api.floom.dev by default.

Example workers

Browse workers/ for the full set. A few useful examples:

  • csv_enricher: enriches CSV rows using custom instructions.
  • research_brief: generates markdown research briefs and can require approval.
  • github-digest: summarizes recent activity on a GitHub repo.
  • outbound-approval-demo: demonstrates a two-run human-in-the-loop approval pattern.
  • gmail-summarize-latest / gmail-smart-replies: Gmail automation templates.

4. Deploy safely

For a self-hosted deployment:

  1. Set FLOOM_SECRET so API requests require the x-floom-secret header. It is member-scoped by default; add WORKEROS_SHARED_SECRET_ROLE=admin only if this deployment intentionally uses the shared secret for admin operations.

  2. Run the API without reload:

    cd apps/api
uvicorn main:app --host 0.0.0.0 --port 8000

  3. Point the web app at that API with FLOOM_API_BASE and, if needed, FLOOM_API_SECRET.

  4. Keep FLOOM_WORKERS_DIR and FLOOM_CONTEXTS_DIR outside the source checkout if you want git-backed worker/context history.

  5. Back up data/, your workspace directories, and ~/.config/workeros/secrets.key if you use local encrypted secrets.

Production hardening checklist:

  • Terminate TLS at a reverse proxy or load balancer.
  • Store secrets in your platform secret manager, not in committed files.
  • Use E2B for untrusted worker execution; do not add an in-process runner.
  • Restrict network access to the API and logs.
  • Run the relevant tests before upgrading.

For release tasks and packaging status, see RELEASE-CHECKLIST.md.