worker.yml

The worker file format: identity, trigger, inputs, runtime, outputs, tools, secrets, and approvals.

Bundle shape

A worker bundle has worker.yml plus either run.py for script mode or SKILL.md for agent mode. Floom uploads the bundle, materializes inputs, injects declared secrets and connections, runs the entrypoint, and captures declared outputs.

folder

workers/my-worker/
  worker.yml
  run.py        # script mode
  SKILL.md      # agent mode, instead of run.py
  requirements.txt

Fields

Top level

schema_versionstringrequired

Use 0.3.

namestringrequired

Stable worker slug, usually lowercase with dashes.

titlestringrequired

Human-readable worker name.

descriptionstringrequired

Short card/list description.

versionstringrequired

Bundle version; bump when the source changes.

entrypointstring

Usually run.py or SKILL.md.

long_description, use_cases, example_input, example_output, how_it_works, folder, tagsoptional

Dashboard metadata for cards, overview, search, and grouping.

trigger

trigger.typestringrequired

One of manual, schedule, webhook, or composio.

trigger.cronstring

Cron expression for schedule workers.

trigger.timezonestring

IANA timezone for schedules, for example Europe/Berlin.

trigger.webhook.secretboolean

Require a generated webhook secret for webhook-triggered runs.

exec

exec.modestring

Use pure-script for code or agent for SKILL.md.

exec.entrystringrequired

Entrypoint file; matches run.py or SKILL.md.

exec.runtimestringrequired

Supported values include python311, node22, bash, skill, and none.

exec.runnerstringrequired

Usually e2b.

exec.commandstring

Script mode command, for example python run.py.

exec.inputs[]arrayrequired

Run input fields, described below.

exec.outputs[]arrayrequired

Named outputs Floom renders and validates.

inputs and outputs

inputs[].namestringrequired

Input key passed into the run.

inputs[].kindstringrequired

Use scalar or file.

inputs[].typestring

Scalar type such as string, number, boolean, textarea, select, or url.

inputs[].label, placeholder, default, requiredoptional

UI and validation metadata.

inputs[].enum / optionsstring[]

Allowed values for select inputs.

inputs[].media_type, path, accepts, max_size_mbfile input

File materialization path and upload constraints.

outputs[].name, kind, media_type, path, required, labeloutputrequired

Output declaration. Markdown file outputs render inline; other files are downloadable.

tools, secrets, limits

connections[]array

Declare app connections. Structured entries can set app and allowed_tools.

capabilities.secretsstring[]

Environment variable names the worker can read.

capabilities.connectionsstring[]

Connection names mirrored for capability checks.

capabilities.network.egressboolean

Set true for workers that call external APIs.

approvals.requiredboolean

Pause runs for human approval before completion or side effects.

limitsobject

Agent-loop limits: max_tool_iterations, max_output_tokens, max_total_tokens, timeout_seconds.

resourcesobject

Optional sandbox sizing request: memory_mb, cpu_count.

Example

This is the minimal script-worker shape used by the engine contract.

worker.yml

schema_version: "0.3"
name: text-normalizer
title: Text Normalizer
description: Normalize a text input and return the normalized value.
version: "0.1.0"
entrypoint: run.py
trigger:
  type: manual
exec:
  mode: pure-script
  entry: run.py
  runtime: python311
  runner: e2b
  command: python run.py
  inputs:
    - name: text
      label: Text
      type: string
      kind: scalar
      required: true
  outputs:
    - name: normalized
      label: Normalized text
      type: string
      kind: scalar
      required: true
capabilities:
  network:
    egress: false
  secrets: []
  connections: []

Schedule trigger

trigger

trigger:
  type: schedule
  cron: "0 9 * * MON"
  timezone: "Europe/Berlin"

Agent worker

agent fields

entrypoint: SKILL.md
exec:
  mode: agent
  entry: SKILL.md
  runtime: python311
  runner: e2b
  inputs: []
  outputs:
    - name: summary
      kind: file
      media_type: text/markdown
      path: out/summary.md
      required: true

Validate

Use the CLI contract, templates, and validation before creating a worker. Hosted MCP agents create workers with workers.create by passing worker_yml, run_py, and optional skill_md.

cli

floom workers contract
floom workers templates list
floom workers templates get python-script
floom workers validate ./workers/<id>
floom workers push ./workers/<id>

Runtime contract

Script workers read inputs.json and write result.json. Agent workers put instructions in SKILL.md and declare outputs in worker.yml so Floom can render and validate them.

The CLI and MCP references are here: CLI workers and MCP tools.